From 5f8b7167a513eb1b0129bdac8542df92b93fc491 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 30 Oct 2020 13:57:23 -0600 Subject: [PATCH] What if we versioned the whole spec? --- proposals/2844-global-versioning.md | 101 ++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 proposals/2844-global-versioning.md diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md new file mode 100644 index 00000000..8ab1d982 --- /dev/null +++ b/proposals/2844-global-versioning.md @@ -0,0 +1,101 @@ +# 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. + +**Note**: This proposal does nothing to room versions and are thus not included beyond this line. + +## 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, 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. + +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/`. + +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`.