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
5 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