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.pull/977/head
Travis Ralston
6 years ago
parent
258aba5fed
commit
71e6321f4d
@ -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.
|
|
||||||
@ -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}-}
|
|
||||||
Loading…
Reference in New Issue