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 <1389908+richvdh@users.noreply.github.com>

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/room_versions/newsfragments/3683.clarification.1

@@ -0,0 +1 @@
+Fix heading order of room version specifications to be consistent.

changelogs/room_versions/newsfragments/3683.clarification.2

@@ -0,0 +1 @@
+Add missing "Signing key validity period" section to room version 6.

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

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`.

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" %}}

content/rooms/v2.md

@@ -36,9 +36,9 @@ 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
 
@@ -46,10 +46,10 @@ 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" %}}

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,16 +93,15 @@ 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" %}}
@@ -106,7 +109,3 @@ completeness.
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}

content/rooms/v4.md

@@ -53,26 +53,14 @@ 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),
@@ -80,3 +68,15 @@ 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" %}}

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" %}}

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" %}}

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" %}}

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
 

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
 

meta/documentation_style.rst

@@ -19,8 +19,8 @@ nested titles (h6, or 6 `#` characters) and instead re-evaluate the document str
 Correct capitalisation for long section names
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Headings should start with a capital letter, and use lower-case otherwise. This
-document is an example of what we mean.
+Headings should be in `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`,
+as represented by this document.
 
 TODOs
 -----
@@ -68,10 +68,29 @@ Lists should:
 
 When talking about properties in JSON objects, prefer the word "property" to "field",
 "member", or various other alternatives. For example: "this property will be set to
-X if ...". Also avoid the term "key" unless you are specifically talking about the 
+X if ...". Also avoid the term "key" unless you are specifically talking about the
 *name* of a property - and be mindful of the scope for confusion with cryptographic
 keys.
 
+Changes between spec versions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sections should reference the Matrix spec version they were added/changed in. This
+is often a guess at what the next version will be - please use the currently released
+version with a minor version bump as the referenced version. For example, if the
+current version is `v1.1` then annotate your changes with `v1.2`.
+
+"Added/changed in" tags can be documented as the following:
+
+* `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents.
+* `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI.
+
+In rare cases, `this=true` can be used on the Markdown syntax to adjust the wording.
+This is most commonly used in room version specifications.
+
+**Tip**: If you're trying to inline the Markdown version and getting unexpected results,
+try replacing the `%` symbols with `<` and `>`, changing how Hugo renders the shortcode.
+
 OpenAPI
 ~~~~~~~
 
@@ -101,3 +120,62 @@ When writing OpenAPI specifications for the API endpoints, follow these rules:
   Some descriptions start with the word "Optional" to explicitly mark optional
   properties and parameters. This is redundant. Instead, use the ``required``
   property to mark those that are required.
+
+Room versions
+~~~~~~~~~~~~~
+
+Room versions are fully specified to cover the entirety of their composition for
+client and server implementations to reference. As such, they have a relatively
+strict format that must be followed, described below.
+
+These rules do not affect MSCs.
+
+The introduction must cover:
+
+* The version the new room version builds on, if any.
+* A brief (one or two line) description of what the room version is expected to
+  consist of. For example, "..., adding new redaction rules to cover memberships".
+
+The next section must then be "Client considerations" to help client developers avoid
+the naturally complex "Server implementation components" later on. This section must:
+
+* Clearly describe any and all changes which affect users of the Client-Server API.
+* Clearly make reference to the redaction rules. A copy/paste example of this is in
+  Room Version 3: "Though unchanged in this room version, clients which implement the
+  redaction algorithm locally should refer to the [redactions] section below for a full
+  overview."
+
+The next section must then be "Server implementation components". This section must:
+
+* Start with the copy/pasted warning that clients should skip or ignore the section.
+* Repeat the introduction using server-focused language. This includes repeating which
+  room version, if any, the room version builds upon.
+* Clearly describe any and all changes which affect server implementations. This
+  includes a "Redactions" section, even if covered by the client considerations section.
+  See Room Version 9 for an example.
+
+Finally, the last section must then be an "Unchanged since vX" section, where ``vX``
+is the room version the version builds upon. If the room version doesn't build upon
+another room version, this section is excluded.
+
+In each of the client, server, and unchanged sections the subheadings must be in the
+following order:
+
+* Redactions
+* Handling redactions (if applicable)
+* Event IDs (if applicable)
+* Event format
+* Authorization rules
+* State resolution
+* Canonical JSON
+* Signing key validity period (if applicable)
+
+Within a given room version, these subheadings must appear at least once. Applicability
+of the headings depends on the room version a new version builds upon: if the underlying
+room version contains the subheading, the new room version must also contain the subheading.
+
+The subheadings which are always deemed as client-affecting are:
+
+* Redactions
+
+When a new subheading is added, it must be referenced and ordered in this document.