Merge 6264b34caf into f92c3579ac

changelogs/room_versions/newsfragments/2297.clarification

@@ -0,0 +1 @@
+Clarify meaning of floating-point powerlevels.

content/rooms/fragments/v1-floaty-power-levels.md

@@ -0,0 +1,40 @@
+
+##### `m.room.power_levels` events accept values as floats
+
+When the value is a float, anything after the decimal point is removed,
+making e.g. `5.17`, `5.42`, and `5` functionally identical. 
+
+For example, this is a valid `m.room.power_levels` event in this room version:
+
+```json
+{
+  "content": {
+    "ban": 50,
+    "events": {
+      "m.room.power_levels": 100
+    },
+    "events_default": 0,
+    "state_default": 50,
+    "users": {
+      "@example:example.org": 100,
+      "@alice:localhost": 50,
+      "@bob:localhost": 50.57
+    },
+    "users_default": 0
+  },
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
+  "sender": "@example:example.org",
+  "state_key": "",
+  "type": "m.room.power_levels"
+}
+```
+
+In this example, both `@bob:localhost` and `@alice:localhost` have the same effective
+power level of `50`, even though the values are technically different.
+
+When a float written in exponential notation is unpacked, the decimal portion is removed
+afterward; for example, `5.114698E4` becomes `51146.98`, which is then truncated to `51146`.
+
+Note that, since this room version does not enforce that events comply with the requirements
+of [Canonical JSON](/appendices#canonical-json), power levels can be formatted as floats.

content/rooms/v1.md

@@ -59,6 +59,8 @@ Events in version 1 rooms have the following structure:
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v1-auth-rules" %}}

content/rooms/v2.md

@@ -57,6 +57,8 @@ Events in rooms of this version have the following structure:
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v1-auth-rules" %}}

content/rooms/v3.md

@@ -87,6 +87,8 @@ The complete structure of a event in a v3 room is shown below.
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% boxes/note %}}

content/rooms/v4.md

@@ -76,6 +76,8 @@ the changes in this room version.
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v3-auth-rules" %}}

content/rooms/v5.md

@@ -58,6 +58,8 @@ completeness.
 
 {{% rver-fragment name="v1-stringy-power-levels" %}}
 
+{{% rver-fragment name="v1-floaty-power-levels" %}}
+
 ### Authorization rules
 
 {{% rver-fragment name="v3-auth-rules" %}}