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.
This commit is contained in:
Travis Ralston
parent
258aba5fed
commit
71e6321f4d
11 changed files with 91 additions and 268 deletions
1
changelogs/rooms/newsfragments/.gitignore
vendored
1
changelogs/rooms/newsfragments/.gitignore
vendored
|
|
@ -1 +0,0 @@
|
|||
!.gitignore
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
[tool.towncrier]
|
||||
filename = "../rooms.rst"
|
||||
directory = "newsfragments"
|
||||
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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))
|
||||
|
|
|
|||
|
|
@ -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_gateway/"+push_gw_ver+".html>`_",
|
||||
push_gw_ver,
|
||||
"Push notifications for Matrix events",
|
||||
), TypeTableRow(
|
||||
"`Rooms <rooms/"+room_ver+".html>`_",
|
||||
room_ver,
|
||||
"Specification for behaviour of rooms, such as event formats",
|
||||
),
|
||||
])
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <rooms/v1.html>`_ - The current version of most rooms.
|
||||
* `Version 2 <rooms/v2.html>`_ - **Beta**. Implements State Resolution Version 2.
|
||||
|
||||
Specification Versions
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <v1.html>`_ - The current version of most rooms.
|
||||
* `Version 2 <v2.html>`_ - Currently in development.
|
||||
|
||||
.. Note: the 'unstable' version is commented out pending a real release of rooms v2
|
||||
.. See meta/releasing-rooms-v2.md
|
||||
.. * `Unstable <unstable.html>`_ - The upcoming version of the room specification.
|
||||
|
|
@ -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 <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
|
||||
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
|
||||
|
||||
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}-}
|
||||
|
|
@ -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 <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
|
||||
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
|
||||
|
||||
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
|
||||
--------------------------------
|
||||
|
|
|
|||
|
|
@ -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 <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
|
||||
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
|
||||
|
||||
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 <v1.html>`_ with an improved state
|
||||
resolution algorithm.
|
||||
|
||||
Server implementation components
|
||||
--------------------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue