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>
pull/977/head
Travis Ralston 3 years ago committed by GitHub
parent 990dfec94b
commit d4c74d37a9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

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

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

@ -5,7 +5,7 @@ toc_hide: true
{{% added-in this=true %}} In room versions 1 and 2, redactions were {{% added-in this=true %}} In room versions 1 and 2, redactions were
explicitly part of the [authorization rules](/rooms/v1/#authorization-rules) explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
under Rule 11. As of room version 3, these conditions no longer exist as 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 While redactions are always accepted by the authorization rules for
events, they should not be sent to clients until both the redaction events, they should not be sent to clients until both the redaction

@ -10,5 +10,5 @@ Base64](/appendices#unpadded-base64) which replaces the 62nd and
matches [RFC4648's definition of URL-safe matches [RFC4648's definition of URL-safe
base64](https://tools.ietf.org/html/rfc4648#section-5). 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`. `$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.

@ -38,6 +38,20 @@ should be aware that restrictions should be generally relaxed and that
inconsistencies may occur. inconsistencies may occur.
{{% /boxes/warning %}} {{% /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 ### State resolution
{{% boxes/warning %}} {{% 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 `event_ids` for the same `(event_type, state_key)`. The events thus
affected are said to be *conflicting* events. 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 ### Canonical JSON
{{% rver-fragment name="v1-canonical-json" %}} {{% rver-fragment name="v1-canonical-json" %}}

@ -36,9 +36,9 @@ changing only the state resolution algorithm.
The following sections have not been modified since v1, but are included for The following sections have not been modified since v1, but are included for
completeness. completeness.
### Authorization rules ### Redactions
{{% rver-fragment name="v1-auth-rules" %}} {{% rver-fragment name="v1-redactions" %}}
### Event format ### Event format
@ -46,10 +46,10 @@ Events in rooms of this version have the following structure:
{{% definition path="api/server-server/definitions/pdu" %}} {{% 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" %}}

@ -37,6 +37,11 @@ use cases should reference.
Room version 3 uses the event format described here in addition to Room version 3 uses the event format described here in addition to
all the remaining behaviour described by [room version 2](/rooms/v2). 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 ### Event IDs
{{% boxes/rationale %}} {{% 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" %}} {{% definition path="api/server-server/definitions/pdu_v3" %}}
### Authorization rules
### Authorization rules for events
{{% added-in this=true %}} `m.room.redaction` events are no longer {{% added-in this=true %}} `m.room.redaction` events are no longer
explicitly part of the auth rules. They are still subject to the 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 --> <!-- set withVersioning=true so we get all the "new in this version" stuff -->
{{% rver-fragment name="v3-auth-rules" withVersioning=true %}} {{% 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 ## Unchanged from v2
The following sections have not been modified since v2, but are included for The following sections have not been modified since v2, but are included for
completeness. completeness.
### Redactions
{{% rver-fragment name="v1-redactions" %}}
### State resolution ### State resolution
{{% rver-fragment name="v2-state-res" %}} {{% rver-fragment name="v2-state-res" %}}
@ -106,7 +109,3 @@ completeness.
### Canonical JSON ### Canonical JSON
{{% rver-fragment name="v1-canonical-json" %}} {{% rver-fragment name="v1-canonical-json" %}}
### Redactions
{{% rver-fragment name="v1-redactions" %}}

@ -53,26 +53,14 @@ generally made administration harder.
The following sections have not been modified since v3, but are included for The following sections have not been modified since v3, but are included for
completeness. completeness.
### State resolution ### Redactions
{{% rver-fragment name="v2-state-res" %}}
### Authorization rules
{{% rver-fragment name="v3-auth-rules" %}} {{% rver-fragment name="v1-redactions" %}}
### Handling redactions ### Handling redactions
{{% rver-fragment name="v3-handling-redactions" %}} {{% rver-fragment name="v3-handling-redactions" %}}
### Canonical JSON
{{% rver-fragment name="v1-canonical-json" %}}
### Redactions
{{% rver-fragment name="v1-redactions" %}}
### Event format ### Event format
The event format is the same as [room version 3](/rooms/v3#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. the changes in this room version.
{{% rver-fragment name="v4-event-format" %}} {{% 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" %}}

@ -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 The following sections have not been modified since v4, but are included for
completeness. completeness.
### State resolution ### Redactions
{{% rver-fragment name="v2-state-res" %}}
### Authorization rules
{{% rver-fragment name="v3-auth-rules" %}} {{% rver-fragment name="v1-redactions" %}}
### Handling redactions ### Handling redactions
@ -55,10 +51,14 @@ completeness.
{{% rver-fragment name="v4-event-format" %}} {{% 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" %}}

@ -38,7 +38,7 @@ in [room version 5](/rooms/v5).
[See above](#redactions). [See above](#redactions).
### Authorization rules for events ### Authorization rules
`m.room.redaction` events are not explicitly part of the auth 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 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 The following sections have not been modified since v5, but are included for
completeness. completeness.
### State resolution ### Handling redactions
{{% rver-fragment name="v2-state-res" %}} {{% rver-fragment name="v3-handling-redactions" %}}
### Event IDs ### Event IDs
@ -212,6 +212,10 @@ completeness.
{{% rver-fragment name="v4-event-format" %}} {{% 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" %}}

@ -188,9 +188,13 @@ Some consequences of these rules:
The following sections have not been modified since v6, but are included for The following sections have not been modified since v6, but are included for
completeness. 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 ### Event IDs
@ -200,9 +204,9 @@ completeness.
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v4-event-format" %}}
### Handling redactions ### State resolution
{{% rver-fragment name="v3-handling-redactions" %}} {{% rver-fragment name="v2-state-res" %}}
### Canonical JSON ### Canonical JSON
@ -211,7 +215,3 @@ completeness.
### Signing key validity period ### Signing key validity period
{{% rver-fragment name="v5-signing-requirements" %}} {{% rver-fragment name="v5-signing-requirements" %}}
### Redactions
{{% rver-fragment name="v6-redactions" %}}

@ -98,9 +98,9 @@ and 4.3.5).
The following sections have not been modified since v7, but are included for The following sections have not been modified since v7, but are included for
completeness. completeness.
### State resolution ### Handling redactions
{{% rver-fragment name="v2-state-res" %}} {{% rver-fragment name="v3-handling-redactions" %}}
### Event IDs ### Event IDs
@ -110,9 +110,9 @@ completeness.
{{% rver-fragment name="v4-event-format" %}} {{% rver-fragment name="v4-event-format" %}}
### Handling redactions ### State resolution
{{% rver-fragment name="v3-handling-redactions" %}} {{% rver-fragment name="v2-state-res" %}}
### Canonical JSON ### Canonical JSON

@ -90,13 +90,9 @@ following considerations.
The following sections have not been modified since v8, but are included for The following sections have not been modified since v8, but are included for
completeness. completeness.
### State resolution ### Handling redactions
{{% rver-fragment name="v2-state-res" %}}
### Authorization rules
{{% rver-fragment name="v8-auth-rules" %}} {{% rver-fragment name="v3-handling-redactions" %}}
### Event IDs ### Event IDs
@ -106,9 +102,13 @@ completeness.
{{% rver-fragment name="v4-event-format" %}} {{% 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 ### Canonical JSON

@ -19,8 +19,8 @@ nested titles (h6, or 6 `#` characters) and instead re-evaluate the document str
Correct capitalisation for long section names Correct capitalisation for long section names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Headings should start with a capital letter, and use lower-case otherwise. This Headings should be in `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`,
document is an example of what we mean. as represented by this document.
TODOs TODOs
----- -----
@ -72,6 +72,25 @@ X if ...". Also avoid the term "key" unless you are specifically talking about t
*name* of a property - and be mindful of the scope for confusion with cryptographic *name* of a property - and be mindful of the scope for confusion with cryptographic
keys. 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 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 Some descriptions start with the word "Optional" to explicitly mark optional
properties and parameters. This is redundant. Instead, use the ``required`` properties and parameters. This is redundant. Instead, use the ``required``
property to mark those that are 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.

Loading…
Cancel
Save