Update documentation style & fix room version heading order (#3683)

* Update documentation style & fix room version heading order Also add a missing signing key section to v6. This additionally contains various edits to the fragments to have them make a little bit more sense in context. Finally, this updates various aspects of the documentation style which haven't previously been considered - they're added here considering we're in the area. * changelog * enhanced changelogs * Minor wording adjustments * Apply suggestions from code review Co-authored-by: Richard van der Hoff <[email protected]> Co-authored-by: Richard van der Hoff <[email protected]>
matrix-org · Jan 31, 2022 · d4c74d3 · d4c74d3
1 parent 990dfec
commit d4c74d3
Show file tree

Hide file tree

Showing 14 changed files with 168 additions and 81 deletions.
diff --git a/changelogs/room_versions/newsfragments/3683.clarification.1 b/changelogs/room_versions/newsfragments/3683.clarification.1
@@ -0,0 +1 @@
+Fix heading order of room version specifications to be consistent.
diff --git a/changelogs/room_versions/newsfragments/3683.clarification.2 b/changelogs/room_versions/newsfragments/3683.clarification.2
@@ -0,0 +1 @@
+Add missing "Signing key validity period" section to room version 6.
diff --git a/content/rooms/fragments/v3-handling-redactions.md b/content/rooms/fragments/v3-handling-redactions.md
@@ -5,7 +5,7 @@ toc_hide: true
 {{% added-in this=true %}} In room versions 1 and 2, redactions were
 explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
 under Rule 11. As of room version 3, these conditions no longer exist as
-represented by the above rules.
+represented by [this version's authorization rules](#authorization-rules).
 
 While redactions are always accepted by the authorization rules for
 events, they should not be sent to clients until both the redaction

diff --git a/content/rooms/fragments/v4-event-ids.md b/content/rooms/fragments/v4-event-ids.md
@@ -10,5 +10,5 @@ Base64](/appendices#unpadded-base64) which replaces the 62nd and
 matches [RFC4648's definition of URL-safe
 base64](https://tools.ietf.org/html/rfc4648#section-5).
 
-Event IDs are still prefixed with `$` and may result in looking like
+Event IDs are still prefixed with `$` and might result in looking like
 `$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.
diff --git a/content/rooms/v1.md b/content/rooms/v1.md
@@ -38,6 +38,20 @@ should be aware that restrictions should be generally relaxed and that
 inconsistencies may occur.
 {{% /boxes/warning %}}
 
+### Redactions
+
+[See above](#redactions).
+
+### Event format
+
+Events in version 1 rooms have the following structure:
+
+{{% definition path="api/server-server/definitions/pdu" %}}
+
+### Authorization rules
+
+{{% rver-fragment name="v1-auth-rules" %}}
+
 ### State resolution
 
 {{% boxes/warning %}}
@@ -97,16 +111,6 @@ A *conflict* occurs between states where those states have different
 `event_ids` for the same `(event_type, state_key)`. The events thus
 affected are said to be *conflicting* events.
 
-### Authorization rules
-
-{{% rver-fragment name="v1-auth-rules" %}}
-
-### Event format
-
-Events in version 1 rooms have the following structure:
-
-{{% definition path="api/server-server/definitions/pdu" %}}
-
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}
diff --git a/content/rooms/v2.md b/content/rooms/v2.md
@@ -36,20 +36,20 @@ changing only the state resolution algorithm.
 The following sections have not been modified since v1, but are included for
 completeness.
 
-### Authorization rules
+### Redactions
 
-{{% rver-fragment name="v1-auth-rules" %}}
+{{% rver-fragment name="v1-redactions" %}}
 
 ### Event format
 
 Events in rooms of this version have the following structure:
 
 {{% definition path="api/server-server/definitions/pdu" %}}
 
-### Canonical JSON
+### Authorization rules
 
-{{% rver-fragment name="v1-canonical-json" %}}
+{{% rver-fragment name="v1-auth-rules" %}}
 
-### Redactions
+### Canonical JSON
 
-{{% rver-fragment name="v1-redactions" %}}
+{{% rver-fragment name="v1-canonical-json" %}}
diff --git a/content/rooms/v3.md b/content/rooms/v3.md
@@ -37,6 +37,11 @@ use cases should reference.
 Room version 3 uses the event format described here in addition to
 all the remaining behaviour described by [room version 2](/rooms/v2).
 
+### Handling redactions
+
+<!-- set withVersioning=true so we get all the "new in this version" stuff -->
+{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
+
 ### Event IDs
 
 {{% boxes/rationale %}}
@@ -76,8 +81,7 @@ The complete structure of a event in a v3 room is shown below.
 
 {{% definition path="api/server-server/definitions/pdu_v3" %}}
 
-
-### Authorization rules for events
+### Authorization rules
 
 {{% added-in this=true %}} `m.room.redaction` events are no longer
 explicitly part of the auth rules. They are still subject to the
@@ -89,24 +93,19 @@ section below for more information.
 <!-- set withVersioning=true so we get all the "new in this version" stuff -->
 {{% rver-fragment name="v3-auth-rules" withVersioning=true %}}
 
-### Handling redactions
-
-<!-- set withVersioning=true so we get all the "new in this version" stuff -->
-{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
-
 ## Unchanged from v2
 
 The following sections have not been modified since v2, but are included for
 completeness.
 
+### Redactions
+
+{{% rver-fragment name="v1-redactions" %}}
+
 ### State resolution
 
 {{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}
diff --git a/content/rooms/v4.md b/content/rooms/v4.md
@@ -53,30 +53,30 @@ generally made administration harder.
 The following sections have not been modified since v3, but are included for
 completeness.
 
-### State resolution
-
-{{% rver-fragment name="v2-state-res" %}}
-
-### Authorization rules
+### Redactions
 
-{{% rver-fragment name="v3-auth-rules" %}}
+{{% rver-fragment name="v1-redactions" %}}
 
 ### Handling redactions
 
 {{% rver-fragment name="v3-handling-redactions" %}}
 
-### Canonical JSON
-
-{{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}
-
 ### Event format
 
 The event format is the same as [room version 3](/rooms/v3#event-format),
 however the event IDs in the following example are updated to reflect
 the changes in this room version.
 
 {{% rver-fragment name="v4-event-format" %}}
+
+### Authorization rules
+
+{{% rver-fragment name="v3-auth-rules" %}}
+
+### State resolution
+
+{{% rver-fragment name="v2-state-res" %}}
+
+### Canonical JSON
+
+{{% rver-fragment name="v1-canonical-json" %}}
diff --git a/content/rooms/v5.md b/content/rooms/v5.md
@@ -35,13 +35,9 @@ Room version 5 uses the same algorithms defined in [room version
 The following sections have not been modified since v4, but are included for
 completeness.
 
-### State resolution
-
-{{% rver-fragment name="v2-state-res" %}}
-
-### Authorization rules
+### Redactions
 
-{{% rver-fragment name="v3-auth-rules" %}}
+{{% rver-fragment name="v1-redactions" %}}
 
 ### Handling redactions
 
@@ -55,10 +51,14 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Canonical JSON
+### Authorization rules
 
-{{% rver-fragment name="v1-canonical-json" %}}
+{{% rver-fragment name="v3-auth-rules" %}}
 
-### Redactions
+### State resolution
 
-{{% rver-fragment name="v1-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
+
+### Canonical JSON
+
+{{% rver-fragment name="v1-canonical-json" %}}
diff --git a/content/rooms/v6.md b/content/rooms/v6.md
@@ -38,7 +38,7 @@ in [room version 5](/rooms/v5).
 
 [See above](#redactions).
 
-### Authorization rules for events
+### Authorization rules
 
 `m.room.redaction` events are not explicitly part of the auth rules.
 They are still subject to the minimum power level rules, but should always
@@ -200,9 +200,9 @@ Some consequences of these rules:
 The following sections have not been modified since v5, but are included for
 completeness.
 
-### State resolution
+### Handling redactions
 
-{{% rver-fragment name="v2-state-res" %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -212,6 +212,10 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### State resolution
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
+
+### Signing key validity period
+
+{{% rver-fragment name="v5-signing-requirements" %}}
diff --git a/content/rooms/v7.md b/content/rooms/v7.md
@@ -188,9 +188,13 @@ Some consequences of these rules:
 The following sections have not been modified since v6, but are included for
 completeness.
 
-### State resolution
+### Redactions
 
-{{% rver-fragment name="v2-state-res" %}}
+{{% rver-fragment name="v6-redactions" %}}
+
+### Handling redactions
+
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -200,9 +204,9 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### State resolution
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON
 
@@ -211,7 +215,3 @@ completeness.
 ### Signing key validity period
 
 {{% rver-fragment name="v5-signing-requirements" %}}
-
-### Redactions
-
-{{% rver-fragment name="v6-redactions" %}}
diff --git a/content/rooms/v8.md b/content/rooms/v8.md
@@ -98,9 +98,9 @@ and 4.3.5).
 The following sections have not been modified since v7, but are included for
 completeness.
 
-### State resolution
+### Handling redactions
 
-{{% rver-fragment name="v2-state-res" %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -110,9 +110,9 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### State resolution
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON
 

diff --git a/content/rooms/v9.md b/content/rooms/v9.md
@@ -90,13 +90,9 @@ following considerations.
 The following sections have not been modified since v8, but are included for
 completeness.
 
-### State resolution
-
-{{% rver-fragment name="v2-state-res" %}}
-
-### Authorization rules
+### Handling redactions
 
-{{% rver-fragment name="v8-auth-rules" %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -106,9 +102,13 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### Authorization rules
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v8-auth-rules" %}}
+
+### State resolution
+
+{{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Fix heading order of room version specifications to be consistent.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add missing "Signing key validity period" section to room version 6.