wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
* 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>
This commit is contained in:
Travis Ralston 2022-01-31 15:18:58 -07:00 • committed by GitHub
parent 990dfec94b
commit d4c74d37a9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 168 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

84
meta/documentation_style.rst
View file

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