Clarify meaning of floating point m.room.power_levels (#2297)

Signed-off-by: Kierre Sametti vel@riseup.net
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

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,41 @@
+
+##### `m.room.power_levels` events accept values as floats
+
+When the value is a float
+ * First, exponential notation is applied: `5.114698E4` becomes `51146.98`
+ * Second, the value is truncated at the decimal point: `51146.98` becomes `51146`.
+
+Values outside the range represented by IEE754 binary64 (a "double") cause the
+powerlevel event to be rejected, as do `Infinity`, `-Infinity` and `NaN`.
+
+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.
+
+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" %}}

content/rooms/v6.md

@@ -42,7 +42,8 @@ in [room version 5](/rooms/v5).
 ### Event format
 
 {{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
-the `depth` limit has been reduced in this room version.
+the `depth` limit has been reduced in this room version, and numeric values may
+no longer be formatted as floats.
 
 {{% rver-fragment name="v6-event-format" %}}