From d4c74d37a9d5f2625c3b9b46b4b44f61edc2ab9d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 31 Jan 2022 15:18:58 -0700 Subject: [PATCH] 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> --- .../newsfragments/3683.clarification.1 | 1 + .../newsfragments/3683.clarification.2 | 1 + .../rooms/fragments/v3-handling-redactions.md | 2 +- content/rooms/fragments/v4-event-ids.md | 2 +- content/rooms/v1.md | 24 +++--- content/rooms/v2.md | 12 +-- content/rooms/v3.md | 21 +++-- content/rooms/v4.md | 28 +++---- content/rooms/v5.md | 20 ++--- content/rooms/v6.md | 14 ++-- content/rooms/v7.md | 16 ++-- content/rooms/v8.md | 8 +- content/rooms/v9.md | 16 ++-- meta/documentation_style.rst | 84 ++++++++++++++++++- 14 files changed, 168 insertions(+), 81 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/3683.clarification.1 create mode 100644 changelogs/room_versions/newsfragments/3683.clarification.2 diff --git a/changelogs/room_versions/newsfragments/3683.clarification.1 b/changelogs/room_versions/newsfragments/3683.clarification.1 new file mode 100644 index 00000000..0e5de2dd --- /dev/null +++ b/changelogs/room_versions/newsfragments/3683.clarification.1 @@ -0,0 +1 @@ +Fix heading order of room version specifications to be consistent. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/3683.clarification.2 b/changelogs/room_versions/newsfragments/3683.clarification.2 new file mode 100644 index 00000000..d5a8bbca --- /dev/null +++ b/changelogs/room_versions/newsfragments/3683.clarification.2 @@ -0,0 +1 @@ +Add missing "Signing key validity period" section to room version 6. \ No newline at end of file diff --git a/content/rooms/fragments/v3-handling-redactions.md b/content/rooms/fragments/v3-handling-redactions.md index 45ef39bf..13c414fb 100644 --- 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 index 2fad7afa..8df1ec2a 100644 --- 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 index 6763270a..1519873b 100644 --- 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 index e5c932c9..cdc59190 100644 --- a/content/rooms/v2.md +++ b/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" %}} diff --git a/content/rooms/v3.md b/content/rooms/v3.md index baa0fcb0..310c6625 100644 --- 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 + + +{{% 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. {{% rver-fragment name="v3-auth-rules" withVersioning=true %}} -### Handling redactions - - -{{% 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" %}} diff --git a/content/rooms/v4.md b/content/rooms/v4.md index eed6b2ed..01c695ba 100644 --- a/content/rooms/v4.md +++ b/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" %}} diff --git a/content/rooms/v5.md b/content/rooms/v5.md index 387a435f..b4283071 100644 --- 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 index e974edcd..67131371 100644 --- 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 index 2c1816ad..ebe1e643 100644 --- 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 index 63c18717..50a1f065 100644 --- 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 index f61c9af9..285a7640 100644 --- 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 diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index aea495bd..3a17cbd6 100644 --- a/meta/documentation_style.rst +++ b/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 `, +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.