|
|
|
|
# MSC2844: Using a global version number for the entire specification
|
|
|
|
|
|
|
|
|
|
Currently we have 4 kinds of versions, all of which have slightly different use cases and semantics
|
|
|
|
|
which apply:
|
|
|
|
|
|
|
|
|
|
1. The individual API spec document versions, tracked as revisions (`r0.6.1`, for example).
|
|
|
|
|
2. Individual endpoint versioning underneath an API spec document version (`/v1/`, `/v2/`, etc). Note
|
|
|
|
|
that the client-server API currently ties the major version of its spec document version to the
|
|
|
|
|
endpoint, thus making most endpoints under it as `/r0/` (currently).
|
|
|
|
|
3. Room versions to freezing a set of behaviour and algorithms on a per-room basis. These are well
|
|
|
|
|
defined in the spec and are not covered here: https://matrix.org/docs/spec/#room-versions
|
|
|
|
|
4. An overarching "Matrix" version, largely for marketing purposes. So far we've only cut Matrix 1.0
|
|
|
|
|
back when we finalized the initial versions of the spec documents, but have not cut another one
|
|
|
|
|
since.
|
|
|
|
|
|
|
|
|
|
This current system is slightly confusing, but has some drawbacks for being able to compile builds of
|
|
|
|
|
the spec documents (published on matrix.org) and generally try and communicate what supported versions
|
|
|
|
|
an implementation might have. For example, Synapse currently supports 4 different APIs, all of which
|
|
|
|
|
have their own versions, and all of which would need to be considered and compared when validating
|
|
|
|
|
another implementation of Matrix such as a client or push gateway. Instead, Synapse could say it
|
|
|
|
|
supports "Matrix 1.1", making compatibility much easier to determine - this is what this proposal aims
|
|
|
|
|
to define.
|
|
|
|
|
|
|
|
|
|
## Proposal
|
|
|
|
|
|
|
|
|
|
Instead of having per-API versions (`r0.6.1`, etc), we have a version that spans the entire specification.
|
|
|
|
|
This version represents versioning for the index (which has quite a bit of unversioned specification on
|
|
|
|
|
it currently), the APIs, room versions, and the appendices (which are also currently unversioned). This
|
|
|
|
|
effectively makes the marketing version previously mentioned an actual version.
|
|
|
|
|
|
|
|
|
|
Doing this has the benefits previously alluded to:
|
|
|
|
|
|
|
|
|
|
* Implementations of Matrix can now easily compare their supported versions using a single identifier
|
|
|
|
|
without having to (potentially) indicate which API they built support for.
|
|
|
|
|
* Publishing the specification is less likely to contain broken or outdated links due to API versions
|
|
|
|
|
not matching up properly. This is currently an issue where if we want to release a new version of
|
|
|
|
|
the server-server specification then we must also either rebuild or manually fix the blob of HTML
|
|
|
|
|
known as the client-server API to account for the new version - we often forget this step, sometimes
|
|
|
|
|
because it's just too difficult.
|
|
|
|
|
* Explaining to people what version Matrix or any of the documents is at becomes incredibly simplified.
|
|
|
|
|
No longer will we have to explain most of what the introduction to this proposal covers to every new
|
|
|
|
|
person who asks.
|
|
|
|
|
|
|
|
|
|
Structurally, the API documents remain mostly unchanged. We'll still have a client-server API, server-server
|
|
|
|
|
API, etc, but won't have versions associated with those particular documents. This also means they would
|
|
|
|
|
lose their individual changelogs in favour of a more general changelog. An exception to this rule is
|
|
|
|
|
room versions, which are covered later in this proposal.
|
|
|
|
|
|
|
|
|
|
The more general changelog would likely have sections for each API that had changes (client-server,
|
|
|
|
|
server-server, etc), likely indicating if a particular API had no changes between the release for
|
|
|
|
|
completeness - things like the push gateway API are only updated every couple years at best.
|
|
|
|
|
|
|
|
|
|
For the endpoints which are currently individually versioned, specifically everything except the client-server
|
|
|
|
|
API's endpoints, there are no changes. The most this MSC does is formalize that endpoints can have
|
|
|
|
|
per-endpoint versions to them, though this MSC does not attempt to define when/how those versions work.
|
|
|
|
|
|
|
|
|
|
For the client-server API in particular, some changes are needed. For backwards compatibility reasons,
|
|
|
|
|
servers which support the `rN` (`r0.6.1`, etc) series of versions still advertise them as normal. To
|
|
|
|
|
support the new Matrix versions, a server would add the version number of Matrix to the `/versions`
|
|
|
|
|
endpoint: `{"versions":["r0.5.0", "r0.6.0", "v1.1.0"]}`. Servers do not need to advertise every
|
|
|
|
|
patch version as there should not be any significant changes in patch versions. If a server supports
|
|
|
|
|
`v1.1.0`, it also supports `v1.1.7`, for example.
|
|
|
|
|
|
|
|
|
|
The endpoints themselves in the client-server API also get converted to per-endpoint versions, where
|
|
|
|
|
all the `/r0/` endpoints now become `/v1/`.
|
|
|
|
|
|
|
|
|
|
Room versions are a bit special in that they have their own version number and are required to have that
|
|
|
|
|
version number so they can be baked into a room/the protocol. This MSC doesn't propose dropping the
|
|
|
|
|
room version's specification on versioning, though does propose that the (un)stability of a given room
|
|
|
|
|
version is covered by this new Matrix version. This MSC also proposes changing the brewing mechanics
|
|
|
|
|
of how room versions are formed to better suit the proposed versioning plan.
|
|
|
|
|
|
|
|
|
|
**TODO: Brewing mechanics of room versions**
|
|
|
|
|
|
|
|
|
|
For grammar, the Matrix version follows semantic versioning. Semantic versioning is typically used for
|
|
|
|
|
software and not specification though, so here's how it translates:
|
|
|
|
|
|
|
|
|
|
* Major versions indicate that a breaking change happened *somewhere* in the specification. Because we'd
|
|
|
|
|
be under a global version, a breaking change in the push gateway (for example) would mean a breaking
|
|
|
|
|
change for all of Matrix. We will want to avoid incrementing this number as much as humanly possible.
|
|
|
|
|
The endpoints are also versioned invidually, so typically a format change in an endpoint would actually
|
|
|
|
|
be a minor version increase for Matrix.
|
|
|
|
|
* Minor versions indicate new features, endpoints, or other enhancements which are backwards compatible
|
|
|
|
|
in nature. This is the number we strive to increase most often.
|
|
|
|
|
* Patch versions are when the changes are solely aesthetic, such as clarifications to the specification,
|
|
|
|
|
spelling error fixes, styling/organizational changes, etc.
|
|
|
|
|
|
|
|
|
|
If accepted, this MSC will declare the spec as it is at the time as Matrix v1.1.0.
|
|
|
|
|
|
|
|
|
|
## Potential issues / alternatives
|
|
|
|
|
|
|
|
|
|
To be completed.
|
|
|
|
|
|
|
|
|
|
## Alternatives
|
|
|
|
|
|
|
|
|
|
To be completed.
|
|
|
|
|
|
|
|
|
|
## Security considerations
|
|
|
|
|
|
|
|
|
|
None relevant - if we need to make a security release for Matrix then we simply make a release and
|
|
|
|
|
advertise accordingly.
|
|
|
|
|
|
|
|
|
|
## Unstable prefix
|
|
|
|
|
|
|
|
|
|
It's not recommended by this MSC to implement this proposal before it lands in the specification, however
|
|
|
|
|
if an implementation wishes to do so then it can advertise `org.matrix.msc2844` in the `unstable_features`
|
|
|
|
|
section of `/versions`, and use `/_matrix/client/unstable/org.matrix.msc2844` in place of
|
|
|
|
|
`/_matrix/client/r0`.
|
