From 71e6321f4d448d840bfb6634d3ee381876d35a97 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 16 Jan 2019 16:57:45 -0700 Subject: [PATCH] Rework how room versions are represented Versions are actually on a scale of recommendations, and are expected to be created as needed. The scale presented here (develop/beta/default/recommended/mandatory) is a more wordy version of what was previously discussed/intended for room versions - the labels aren't final and may be changed. --- changelogs/rooms/newsfragments/.gitignore | 1 - changelogs/rooms/pyproject.toml | 30 -------- meta/releasing-rooms-v2.md | 38 --------- scripts/gendoc.py | 5 -- scripts/templating/matrix_templates/units.py | 5 -- specification/index.rst | 81 ++++++++++++++++++++ specification/rooms/intro.rst | 70 ----------------- specification/rooms/unstable.rst | 54 ------------- specification/rooms/v1.rst | 24 ++---- specification/rooms/v2.rst | 30 ++------ specification/targets.yaml | 21 ----- 11 files changed, 91 insertions(+), 268 deletions(-) delete mode 100644 changelogs/rooms/newsfragments/.gitignore delete mode 100644 changelogs/rooms/pyproject.toml delete mode 100644 meta/releasing-rooms-v2.md delete mode 100644 specification/rooms/intro.rst delete mode 100644 specification/rooms/unstable.rst diff --git a/changelogs/rooms/newsfragments/.gitignore b/changelogs/rooms/newsfragments/.gitignore deleted file mode 100644 index b722e9e13..000000000 --- a/changelogs/rooms/newsfragments/.gitignore +++ /dev/null @@ -1 +0,0 @@ -!.gitignore \ No newline at end of file diff --git a/changelogs/rooms/pyproject.toml b/changelogs/rooms/pyproject.toml deleted file mode 100644 index b56e19a96..000000000 --- a/changelogs/rooms/pyproject.toml +++ /dev/null @@ -1,30 +0,0 @@ -[tool.towncrier] - filename = "../rooms.rst" - directory = "newsfragments" - issue_format = "`#{issue} `_" - title_format = "{version}" - - [[tool.towncrier.type]] - directory = "breaking" - name = "Breaking Changes" - showcontent = true - - [[tool.towncrier.type]] - directory = "deprecation" - name = "Deprecations" - showcontent = true - - [[tool.towncrier.type]] - directory = "new" - name = "New Endpoints" - showcontent = true - - [[tool.towncrier.type]] - directory = "feature" - name = "Backwards Compatible Changes" - showcontent = true - - [[tool.towncrier.type]] - directory = "clarification" - name = "Spec Clarifications" - showcontent = true diff --git a/meta/releasing-rooms-v2.md b/meta/releasing-rooms-v2.md deleted file mode 100644 index 802777493..000000000 --- a/meta/releasing-rooms-v2.md +++ /dev/null @@ -1,38 +0,0 @@ -# How to release Room Version 2 - -Room versions are a bit special for the release given they have been -introduced at v2 rather than ever getting a v1 release. Additionally, -room versions have different release requirements due to the in-project -versioning of documents rather than relying on matrix.org to maintain -old generated output of specifications. - -As of writing, the project is structured to support 3 logical versions -for rooms: v1, v2, and unstable. Unstable is currently pointed at v2 -in order to aid development. After v2 is released, unstable may wish -to be left as an independent version or similarly be pointed at a "v3" -document. - -Due to room versions being versioned in-project, the generated output -from a release is not to be sent off to matrix-doc/matrix.org. Instead, -in `gendoc.py` the default value for `--room_version` should be set to -the current release (`v2`, for example) so the index renders the right -edition in the table. - -After editing `gendoc.py`, the changelog should be generated according -to the towncrier instructions. You may need to fix the `.. version: v2` -comment located in the `rooms.rst` changelog to be just underneath the -title instead of at the end of the section. - -The `targets.yaml` file needs to be set up to point unstable to the -right set of files. Ensure that `unstable.rst` is referenced instead -of `v2.rst`, and that `unstable.rst` has appropriate contents. - -Finally, in the `intro.rst` for room versions, re-add unstable to the -list of available versions. It is currently commented out to avoid -confusing people, so it should be possible to uncomment it and put it -back into the list. - -From there, the standard process of using a release branch, tagging it, -and announcing it to the world should be followed. If required, the -various other APIs should be updated to better support the new room -version. diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 0455c90ab..72e3047cf 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -529,10 +529,6 @@ if __name__ == '__main__': "--identity_release", "-i", action="store", default="unstable", help="The identity service release tag to generate, e.g. r1.2" ) - parser.add_argument( - "--room_version", "-r", action="store", default="unstable", - help="The current room version to advertise, e.g. v2" - ) parser.add_argument( "--list_targets", action="store_true", help="Do not update the specification. Instead print a list of targets.", @@ -559,7 +555,6 @@ if __name__ == '__main__': "%APPSERVICE_RELEASE_LABEL%": args.appservice_release, "%IDENTITY_RELEASE_LABEL%": args.identity_release, "%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release, - "%CURRENT_ROOM_VERSION%": args.room_version, } exit (main(args.target or ["all"], args.dest, args.nodelete, substitutions)) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 666434a53..721501ff5 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -757,7 +757,6 @@ class MatrixUnits(Units): is_ver = substitutions.get("%IDENTITY_RELEASE_LABEL%", "unstable") as_ver = substitutions.get("%APPSERVICE_RELEASE_LABEL%", "unstable") push_gw_ver = substitutions.get("%PUSH_GATEWAY_RELEASE_LABEL%", "unstable") - room_ver = substitutions.get("%CURRENT_ROOM_VERSION%", "unstable") # we abuse the typetable to return this info to the templates return TypeTable(rows=[ @@ -781,10 +780,6 @@ class MatrixUnits(Units): "`Push Gateway API `_", push_gw_ver, "Push notifications for Matrix events", - ), TypeTableRow( - "`Rooms `_", - room_ver, - "Specification for behaviour of rooms, such as event formats", ), ]) diff --git a/specification/index.rst b/specification/index.rst index bb9187393..2f17ec298 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -418,6 +418,87 @@ dedicated API. The API is symmetrical to managing Profile data. Would it really be overengineered to use the same API for both profile & private user data, but with different ACLs? + +Room Versions +------------- + +Rooms are central to how Matrix operates, and have strict rules for what +is allowed to be contained within them. Rooms can also have various +algorithms that handle different tasks, such as what to do when two or +more events collide in the underlying DAG. To allow rooms to be improved +upon through new algorithms or rules, "room versions" are employed to +manage a set of expectations for each room. New room versions are assigned +as needed. + +Room version grammar +~~~~~~~~~~~~~~~~~~~~ + +Room versions are used to change properties of rooms that may not be compatible +with other servers. For example, changing the rules for event authorization would +cause older servers to potentially end up in a split-brain situation due to them +not understanding the new rules. + +A room version is defined as a string of characters which MUST NOT exceed 32 +codepoints in length. Room versions MUST NOT be empty and SHOULD contain only +the characters ``a-z``, ``0-9``, ``.``, and ``-``. + +Room versions are not intended to be parsed and should be treated as opaque +identifiers. Room versions consisting only of the characters ``0-9`` and ``.`` +are reserved for future versions of the Matrix protocol. + +The complete grammar for a legal room version is:: + + room_version = 1*room_version_char + room_version_char = DIGIT + / %x61-7A ; a-z + / "-" / "." + +Examples of valid room versions are: + +* ``1`` (would be reserved by the Matrix protocol) +* ``1.2`` (would be reserved by the Matrix protocol) +* ``1.2-beta`` +* ``com.example.version`` + +Recommended room versions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are varying degrees of what "recommended" means for a given room version. +Currently, this is split into 5 categories: + +* **Development**: This is the default state for all room versions. When in this + state, a room version is documented but not recommended for use outside of a + development environment. These versions are not production-ready. +* **Beta**: Versions in this state are not intended for wide-spread usage but + should be stable enough if a room requires the feature(s) introduced within. + Rooms will need to opt-in to these versions and should not be promoted to + upgrade. +* **Default**: Exactly 1 room version will be in this category. The version under + this category should be used when creating rooms (unless another version is + requested by the user). Servers may wish to promote rooms to opt-in to this + version. +* **Recommended**: Exactly 1 room version will be in this category as well. The + version here should be heavily promoted by servers for rooms to opt-in to using. + This version is often going to be the same as the Default version. +* **Mandatory**: Servers are required to implement versions in this category. When + a version is flagged as mandatory, additional rules may apply to rooms. For example, + servers may be required to stop supporting another room version and automatically + upgrade all affected rooms. + +With the above categories, the following applies: + +* Servers MUST have Room Version 1 as the Default room version. +* Servers MUST have Room Version 1 as the Recommended room version. +* Servers MUST implement Room Version 1 as a Mandatory room version. + +Complete list of room versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The available room versions are: + +* `Version 1 `_ - The current version of most rooms. +* `Version 2 `_ - **Beta**. Implements State Resolution Version 2. + Specification Versions ---------------------- diff --git a/specification/rooms/intro.rst b/specification/rooms/intro.rst deleted file mode 100644 index 6231d066b..000000000 --- a/specification/rooms/intro.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. Copyright 2018 New Vector Ltd -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. - -Room Specification -================== - -.. contents:: Table of Contents -.. sectnum:: - -Rooms are central to how Matrix operates, and have strict rules for what -is allowed to be contained within them. Rooms can also have various -algorithms that handle different tasks, such as what to do when two or -more events collide in the underlying DAG. To allow rooms to be improved -upon through new algorithms or rules, "room versions" are employed to -manage a set of expectations for each room. - - -Room version grammar --------------------- - -Room versions are used to change properties of rooms that may not be compatible -with other servers. For example, changing the rules for event authorization would -cause older servers to potentially end up in a split-brain situation due to them -not understanding the new rules. - -A room version is defined as a string of characters which MUST NOT exceed 32 -codepoints in length. Room versions MUST NOT be empty and SHOULD contain only -the characters ``a-z``, ``0-9``, ``.``, and ``-``. - -Room versions are not intended to be parsed and should be treated as opaque -identifiers. Room versions consisting only of the characters ``0-9`` and ``.`` -are reserved for future versions of the Matrix protocol. - -The complete grammar for a legal room version is:: - - room_version = 1*room_version_char - room_version_char = DIGIT - / %x61-7A ; a-z - / "-" / "." - -Examples of valid room versions are: - -* ``1`` (would be reserved by the Matrix protocol) -* ``1.2`` (would be reserved by the Matrix protocol) -* ``1.2-beta`` -* ``com.example.version`` - - -Other room versions -------------------- - -The available room versions are: - -* `Version 1 `_ - The current version of most rooms. -* `Version 2 `_ - Currently in development. - -.. Note: the 'unstable' version is commented out pending a real release of rooms v2 -.. See meta/releasing-rooms-v2.md -.. * `Unstable `_ - The upcoming version of the room specification. diff --git a/specification/rooms/unstable.rst b/specification/rooms/unstable.rst deleted file mode 100644 index 44261814f..000000000 --- a/specification/rooms/unstable.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. Copyright 2018 New Vector Ltd -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. - - -.. DEV NOTE: This is stubbed as a template and not actually used anywhere. -.. See v2.rst for the "unstable" room version, which is currently under -.. development. -.. -.. See meta/releasing-rooms-v2.md - - -.. Note: This document appended to the end of the intro, so this next line -.. appears under "Other Room Versions". - -.. Warning:: - - This is the specification for unreleased changes to rooms. The stability - of rooms using this specification cannot be guaranteed. - - -Changelog ---------- - -.. topic:: unstable -{{rooms_changelog_unstable}} - -This version of the specification is generated from -`matrix-doc `_ as of Git commit -`{{git_version}} `_. - -For the full historical changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/changelogs/rooms.rst - - -Some Module ------------ - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sit amet -eros turpis. Quisque commodo diam vel massa ultrices, vel egestas eros -dignissim. Sed sit amet lacus eget metus auctor malesuada at ut odio. -In turpis leo, viverra et mi porttitor, condimentum bibendum dolor. - -.. {-{versioned_test_definition}-} diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index 6c6795a4f..c263a1080 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -1,4 +1,4 @@ -.. Copyright 2018 New Vector Ltd +.. Copyright 2018-2019 New Vector Ltd .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -12,25 +12,11 @@ .. See the License for the specific language governing permissions and .. limitations under the License. +Room Version 1 +============== -.. Note: This document appended to the end of the intro, so this next line -.. appears under "Other Room Versions". - -This is the specification for **room version 1** (``"1"``). - -Changelog ---------- - -.. topic:: Room version 1 -{{rooms_changelog_v1}} - -This version of the specification is generated from -`matrix-doc `_ as of Git commit -`{{git_version}} `_. - -For the full historical changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/changelogs/rooms.rst - +This room version is the first ever version for rooms, and contains the building +blocks for other room versions. Server implementation components -------------------------------- diff --git a/specification/rooms/v2.rst b/specification/rooms/v2.rst index b04f94b4a..eef034977 100644 --- a/specification/rooms/v2.rst +++ b/specification/rooms/v2.rst @@ -1,4 +1,4 @@ -.. Copyright 2018 New Vector Ltd +.. Copyright 2018-2019 New Vector Ltd .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -12,31 +12,11 @@ .. See the License for the specific language governing permissions and .. limitations under the License. +Room Version 2 +============== -.. Note: This document appended to the end of the intro, so this next line -.. appears under "Other Room Versions". - -This is the specification for **room version 2** (``"2"``). - -.. Warning:: - - Room version 2 is under development and cannot be relied on in production - environments. - - -Changelog ---------- - -.. topic:: Room version 2 -{{rooms_changelog_v2}} - -This version of the specification is generated from -`matrix-doc `_ as of Git commit -`{{git_version}} `_. - -For the full historical changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/changelogs/rooms.rst - +This room version builds off of `version 1 `_ with an improved state +resolution algorithm. Server implementation components -------------------------------- diff --git a/specification/targets.yaml b/specification/targets.yaml index b940148da..e966f66b0 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -26,35 +26,14 @@ targets: files: - push_gateway.rst version_label: "%PUSH_GATEWAY_RELEASE_LABEL%" - rooms: - files: - - rooms/intro.rst - - # TODO: Switch this back to unstable.rst after releasing rooms v2 - # We temporarily do this so that "unstable" points to the in-dev - # version, however we may also want to hardlink to v2 in places and - # thus we maintain a v2 version of the same doc. - # - # See meta/releasing-rooms-v2.md - - #- rooms/unstable.rst - - rooms/v2.rst - version_label: unstable rooms@v1: # this is translated to be rooms/v1.html files: - - rooms/intro.rst - rooms/v1.rst version_label: v1 rooms@v2: # this is translated to be rooms/v2.html files: - - rooms/intro.rst - rooms/v2.rst version_label: v2 - rooms@latest: # this is translated to be rooms/latest.html - files: - - rooms/intro.rst - - rooms/v1.rst # TODO: Find a better way to link to the v2 spec - version_label: latest appendices: files: - appendices.rst