What if we versioned the whole spec?

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`.