ffe577371d
The "Room Specification" (or "Room Version Specification") is the specification that defines which room versions do what and are intended to be documents which speak the truth about how rooms operate under the hood. The approach taken here is a bit different than other specifications. For starters, the specification is versioned in this project instead of relying on the matrix.org repository to track compiled HTML. This is done for a couple reasons, the first being we're still developing the v1 specification while concurrently making a v2 spec and the second being trying to reduce the reliance on matrix.org's repository for specifications. Because the room spec is built into versions, some changes needed to be made. The `targets.yaml` now has a special syntax for indicating what version something is at, and the changelog generator can handle rendering different versions of the same changelog (as parsed from the RST). Some additional work has been put in to the changelog parsing to allow us to reference the v1 room spec as "v1" without having to sacrifice clarity in the changelog headings. Finally, this moves the state resolution algorithms into the versioned spec as a result of MSC1759 (https://github.com/matrix-org/matrix-doc/pull/1759). Note: this does not introduce the concept of versioned schemas (tabs) that I was previously working with. There's currently no use for them, so they are shelved elsewhere.
1.8 KiB
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.