From 5f8b7167a513eb1b0129bdac8542df92b93fc491 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 30 Oct 2020 13:57:23 -0600 Subject: [PATCH 01/14] 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`. From 973ee1438c80df5e8cf9fad51a3ec4f2a3567335 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 10 Nov 2020 12:51:50 -0700 Subject: [PATCH 02/14] Progress checkpoint on room versions --- proposals/2844-global-versioning.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 8ab1d982..6eba7d0c 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -21,14 +21,12 @@ another implementation of Matrix such as a client or push gateway. Instead, Syna 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. +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: @@ -45,7 +43,8 @@ Doing this has the benefits previously alluded to: 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. +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 @@ -65,6 +64,14 @@ patch version as there should not be any significant changes in patch versions. 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: From 4dee8dbeab47ac7a09b49241aa29ede8b35a3ad6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 10 Nov 2020 16:31:53 -0700 Subject: [PATCH 03/14] Versioning WIP --- proposals/2844-global-versioning.md | 178 +++++++++++++++++++++------- 1 file changed, 138 insertions(+), 40 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 6eba7d0c..a3428cfc 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -25,8 +25,13 @@ to define. 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. +it currently), the APIs, room versions, and the appendices (which are also currently unversioned but +contain specification). Room versions are a bit more nuanced though, and are covered later in this MSC. + +The version which covers the entire specification and all its parts is called the "Matrix version", and +is a promotion of the previously marketing-only version number assigned to the spec. Upon acceptance of +this MSC, the Matrix version would be 1.1.0. v1.0 from the marketing era would be recorded somewhere for +posterity, though largely has no significant meaning (unchanged by this MSC). Doing this has the benefits previously alluded to: @@ -41,28 +46,131 @@ Doing this has the benefits previously alluded to: 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/`. +### Full Matrix version grammar + +The Matrix versioning scheme takes heavy inspiration from semantic versioning, though intentionally does +not follow it for reasons described throughout this proposal. Primarily, the argument against semantic +versioning is held in the alternatives section below. + +Given a version number `MAJOR.MINOR.PATCH`, incremement the: + +* `MAJOR` version when a substantial change is made to the core of the protocol. This is reserved for + interpretation by the Spec Core Team, though is intended to be for extremely invasive changes such + as switching away from JSON, introducing a number of features where a `MINOR` version increase just + doesn't feel good enough, or changes to the signing algorithms. +* `MINOR` version when a feature is introduced, or a backwards incompatible change has been managed + through the specification. Later on, this proposal explains what it means to manage a breaking change. +* `PATCH` version when correctional changes are made, such as spelling, cosmetic, or other similarly + small patches are done. Implementations do not need to worry about the patch version. + +When present in the protocol itself, the Matrix version will always be prefixed with `v`. For example, +`v1.1.0`. + +When a dash (`-`) is present after the `PATCH` version, the version is denoting some off-cycle release +information. This is how we'd, for example, make release candidates, alpha, beta, or unstable builds as +needed. This MSC does not propose a scheme for RCs or pre-releases, though the Spec Core Team may wish +to do so. + +See the section on brewing Matrix versions for information on how the unstable version is decided. + +From an implementation perspective, compatibility is guaranteed between `PATCH` versions. `MINOR` versions +have a backwards compatibility scheme described later in this proposal. `MAJOR` versions are expected +to have zero backwards compatibility guarantees to them. + +For clarity, `v1.1.0` and `v1.1.8` are functionally the same. `v1.2.0` will probably work with `v1.1.0`, +though implementations should be wary if they depend on a version. As mentioned, the backwards compatibility +scheme section goes into more detail on this. + +A potential argument is that we don't need a patch version if no implementation will ever care about it, +which is a valid argument to have. This MSC believes that although the patch version is effectively useless +to implementations, it is valuable as evidence of progress and finality of a given version. Going back to +edit already-released versions of the specification can be damaging to the integrity of the protocol, +and thus it is proposed by this MSC that the Spec Core Team remain accountable by forcing them to release +a with a patch version increase for minor, functionally indifferent, changes. + +### Structure changes and changelogs + +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. + +Though the changelog format is not covered by the MSC process, this MSC proposes that the initial +changelog for the Matrix versioning scheme be broken out into sections for each API that had changes. +Ideally, the changelog would also indicate if no changes were made to a particular API/area to help +be clearer to implementation authors. The Push Gateway API is, for example, likely going to be one +of the few which will nearly always say "No relevant changes" for years. + +### Endpoint versioning + +Under this MSC, all HTTP endpoints in the specification are to be per-endpoint versioned. This is already +the case for all APIs except the client-server API, and so this section deals specifically with that API. +The deprecation of endpoints is handled later in this proposal. + +Under this proposal, all endpoints in the client-server API get assigned `v3` as their per-endpoint +version as a starting point. This is primarily done to avoid confusion with the ancient client-server API +versions which had `v1` and called the `rN` system "v2". Though many of the endpoints available today +are not present in those older API editions, it is still proposed that they start at `v3` to avoid +confusion with long-standing implementations. + +Servers which are lucky enough exist during this versioning scheme change are expected to continue +supporting the `rN` system. This is done by advertising the existing client-server API versions as +they always would have on `/versions`, though appending `"v1.1.0"` to indicate that this MSC is +supported. + +As a further clarification to an solved problem, the `/versions` endpoint for the client-server API +does not need to advertise all patch version changes - just the major/minor versions it supports. +If a server does advertise a patch version, clients are expected to resolve that to the relevant +major/minor version equivalent (`v1.1.8` gets treated as `v1.1.0`, for example). + +### Brewing changes for the specification + +Prior to this MSC, the Spec Core Team would release a given version of an API whenever it felt like +the right time to do so. There's very little planning put into a release, and often times the call to +cut a release is arbitrary. Though this MSC doesn't solve this problem neccesarily, it does change +the dynamic the Spec Core Team has with the community when it comes to releases. + +Instead of arbitrarily deciding when to cut a release, the Spec Core Team is expected to plan ahead +and choose a date for the next major/minor release. The team is not required to use a cadence to +perform releases, though is expected to perform at least one release a year. Reasonable notice is +expected to be given to the community to give them a chance to push their MSCs and ideas to +completion. "Reasonable" is intentionally left undefined by this MSC as it might change over time, +though the current suggestion is to give at least 2 months notice. Most MSC authors are currently +contributing on a volunteer or spare time basis and thus might not be able to rapidly push their +ideas through the stages as quickly. + +Patch releases do not require such notice and can happen whenever. + +The date advertised to the community is a cutoff date, not a release date. The Spec Core Team and +wider community might still need time to write up the formal specification for some MSCs or improve +their implementations to be more prepared for the impending official release. In the eyes of the MSC +process, the cutoff date is *not* enough for an implementation to switch to using stable endpoints. + +Considering these are only expectations and not requirements, the Spec Core Team might break them +from time to time for various reasons including urgent security releases, last minute realizations +that something might not work as proposed, etc. Under the Foundation, the Spec Core Team is required +to act in the best interest of the protocol and therefore should be able to reasonably justify why +an expectation is being broken at the time of breaking it - in no way does this MSC propose that +the Spec Core Team be able to blindside the community with a release for no justifiable reason. + +To recap, the process is as follows: + +1. Sometime after a given release happens, the Spec Core Team announces a cutoff date for MSCs to land + that is at least 2 months in the future. +2. Upon cutoff, the Spec Core Team takes responsibility for ensuring all relevant changes are written + up in a timely fashion. +3. The Spec Core Team makes the release. At this point, implementations can stop using unstable + prefixes for any included MSC. + +Because the release schedule is well-advertised, it should be clear to everyone what the next non-patch +version number will be. By default, the assumption can be made that the `MINOR` version will increase +by 1. For the purposes of producing built copies of the spec, the version number for unstable (unreleased) +versions shall be the next *expected* version number followed by `-unstable`. For example, if `v1.1.0` +were the current release, the unstable specification would be built as `v1.2.0-unstable`. In the event +that a change lands where the major version needs incremementing, `v1.2.0` (in this example) would never +see the light of day and instead turn into `v2.0.0-unstable`. + +### Room versions & brewing room versions 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 @@ -72,29 +180,19 @@ 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 +## Potential issues To be completed. +- Drop off patch version? +- When can I stop supporting a version? + ## Alternatives To be completed. +- semver + ## Security considerations None relevant - if we need to make a security release for Matrix then we simply make a release and From 1310c7c8bf4aff233d0c44bdb51181c61d77aa88 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 12 Nov 2020 17:45:26 -0700 Subject: [PATCH 04/14] Finish up the last few sections --- proposals/2844-global-versioning.md | 122 ++++++++++++++++++++++++---- 1 file changed, 108 insertions(+), 14 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index a3428cfc..73a37afe 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -172,26 +172,120 @@ see the light of day and instead turn into `v2.0.0-unstable`. ### Room versions & brewing room versions -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** +*Author's note*: Having many things with the root word "version" can be confusing, so for this section +"room versions" are called "room editions" and the Matrix version refers to what this proposal is +introducing. This MSC does not propose renaming "room versions" - that is another MSC's problem. + +Room editions are a bit special in that they have their own versioning scheme as other servers need to +be aware of how to process the room. As such, a room edition's versioning scheme is not altered by this +proposal, however the publishing of the (in)stability of a given edition is now covered by the newly +proposed Matrix version. + +Whenever a room edition transitions from stable to unstable, or unstable to stable, or is introduced +then it would get counted as a feature for a `MINOR` release of Matrix. We don't currently have a plan +to remove any room editions, so they are not covered as a potential process for this MSC. + +The brewing process for a room edition has typically been a last minute MSC to declare an edition number +and which other MSCs are included. This MSC proposes changing that slightly to instead allow accepted +MSCs to be batched up at release time into a new room edition. Each MSC will have needed testing and +implementation validation prior to their acceptance, so it should be fine to merge them together. If +a concern or conflict were to arise about doing so, an explicit MSC could be raised just like in today's +model where the conflicts/concerns are resolved. Such concerns might be the compatibility of the features, +and some conflicts might be two MSCs changing the same authorization rule (for example). The new, explicit, +MSC would require implementation validation and testing to be approved and thus would then be fine. + +Though somewhat implicit, it might not be clear: multiple room editions can be included in a single Matrix +release, though how they get built is not really addressed by this MSC. Using the spirit of the ideas +proposed, it would likely mean as many MSCs as room editions to bring them into effect. This sort of +practice is believed to be extremely rare, however - it'd be more likely that the Spec Core Team uses +their capability to do an emergency release of Matrix to get a room edition into the wild rather than +brew two (or more) room editions at once. + +The recommended default room edition is not automatically changed under this proposal either - changing +the recommended default requires an MSC just like any other part of Matrix and would fall under general +feature changes. + +### Deprecation approach + +This MSC doesn't change much about how things get deprecated, though it would be codified by this MSC. + +An MSC is required to transition something from stable (the default) to deprecated. Once something has +been deprecated for suitably long enough, it is eligible for removal from the specification with another +MSC. Today's process is the same, though not defined explicitly. + +Also not mentioned in today's system is that implementations are not required to implement deprecated +endpoints. This MSC also changes that and says that they do for versions in which they were deprecated +in. For example, if an endpoint was introduced in v1.1, deprecated in v1.2, and removed in v1.3 then +a server would have to implement the endpoint for v1.1 and v1.2 if it wanted to claim support for those +versions - v1.3 doesn't have the endpoint, so the endpoint's existence is not conditional for being +able to claim support for that version. + +Generally deprecation is paired with replacement or breaking changes. For example, if `/v3/sync` were +to be modified such that it needed to be bumped to `v4`, the MSC which does so would deprecate `/v3/sync` +in favour of its proposed `/v4/sync`. Because endpoints are versioned on a per-endpoint basis, `/v4/sync` +will still work with a server that supports `/v3/profile` (for example) - the version number doesn't mean +an implementation can only use v4 endpoints. + +### Supported versions schedule + +Currently implementations are left to fend for themselves on deciding which versions of their APIs to +support. This MSC doesn't change this due to a wide variety of potential use cases for different +environments and older specifications, though this MSC does bring forth a guiding principle which is +applicable to most standard implementations. + +Implementations are encouraged to support the latest version of Matrix as soon as feasibly possible, +and the two most recent `MINOR` versions past that. Given a cadence of about 1 release every 6 months, +this should mean that the standard implementation supports roughly 1.5 years worth of Matrix history. + +Room versions are special in that they will essentially always be included in a Matrix release, even if +unstable. The current specification says that implementatiosn don't have to implement unstable room +versions, and this is true under this MSC too. + +For extreme clarity, the suggested schedule for supported versions would be (all examples): + +* v1.1.0 - Released in January 2019 - No support needed due to age. +* v1.2.0 - Released in July 2019 - Should be supported as part of the 1.2.x series. +* v1.2.5 - Released in August 2019 - Should be supported because it's part of the 1.2.x series. +* v1.3.0 - Released in December 2019 - Should be supported. +* v1.4.0 - Released in January 2020 - The current release so should definitely be supported. ## Potential issues -To be completed. - -- Drop off patch version? -- When can I stop supporting a version? +None appear to be relevant to be discussed on their own - they are discussed in their respective +sections above when raised. ## Alternatives -To be completed. - -- semver +There are some strong opinions that we should use proper semantic versioning for the specification +instead of the inspired system proposed here. So, why shouldn't we use semantic versioning? + +1. It's meant for software and library compatibility, not specifications. Though it could theoretically + be used as a specification version, the benefits of doing so are not immediately clear. The scheme + proposed here is simple enough where rudimentary comparisons are still possible between versions, + and existing semantic versioning libraries can still be made to work. Further, the specification's + version number should not be relied upon by a library for its versioning scheme - libraries, + applications, etc should have their own versioning scheme so they may work independently of the + spec's release schedule. + +2. It has potential for causing very high major version numbers. Though largely an aesthetic concern, + it can be hard to market Matrix v45 (or even Matrix v4) to potential ecosystem adopters due to + the apparant unstable-ness of the specification. Similarly, the major version is used for advertising + purposes which could be confusing or overly noisy to say there's a major version every few + releases. By instead staying in the 1.x series for a long period of time, the specification appears + stable and easy to work with, attracting potential adopters and making that 2.0 release feel all + that more special. + +3. The semantic versioning spec is not followed in practice. Most uses of semantic versioning are + actually off-spec adaptations which are largely compatible with the ideals of the system. This, however, + puts Matrix in a difficult spot as it would want to say we follow semantic versioning, but can't + because there's no relevant specification document to link to. Even if there was, it would appear + as though we were encouraging the idea of forking a specification as a specification ourselves, + which may be confusing if not sending the wrong message entirely. Though the system proposed here + is a reinvention of semantic versioning to a degree, this proposed system is different from how + semantic versioning works in so many ways it is not entirely comparable. + +4. The benefit of saying we use a well-popularized versioning system is not a strong enough argument + to be considered here. ## Security considerations From d079d7d2d3fa53549f66fcd2c57e5c767cda3232 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 12 Nov 2020 17:51:22 -0700 Subject: [PATCH 05/14] Answer question about confusing deprecation with not --- proposals/2844-global-versioning.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 73a37afe..224430c4 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -226,6 +226,13 @@ in favour of its proposed `/v4/sync`. Because endpoints are versioned on a per-e will still work with a server that supports `/v3/profile` (for example) - the version number doesn't mean an implementation can only use v4 endpoints. +This sort of approach could be potentially confusing and non-standard as it would mean for an amount of +time in the specification there would be two versions of an endpoint: one deprecated and one not. Most +specifications and protocols do not use this sort of approach and instead opt to replace the whole API +or outright remove the endpoint, however the Matrix specification tends to have a longer-lived cycle +associated with it and thus means we should support a larger than average backwards compatibility +period. + ### Supported versions schedule Currently implementations are left to fend for themselves on deciding which versions of their APIs to From 74746634afecd3e9e39a2676e239c1db1b8bfd77 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 19 Nov 2020 08:18:45 -0700 Subject: [PATCH 06/14] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2844-global-versioning.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 224430c4..0204c5e4 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -13,7 +13,7 @@ which apply: 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 +This current system is slightly confusing, and 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 @@ -86,7 +86,7 @@ which is a valid argument to have. This MSC believes that although the patch ver to implementations, it is valuable as evidence of progress and finality of a given version. Going back to edit already-released versions of the specification can be damaging to the integrity of the protocol, and thus it is proposed by this MSC that the Spec Core Team remain accountable by forcing them to release -a with a patch version increase for minor, functionally indifferent, changes. +with a patch version increase for minor, functionally indifferent, changes. ### Structure changes and changelogs @@ -113,12 +113,12 @@ versions which had `v1` and called the `rN` system "v2". Though many of the endp are not present in those older API editions, it is still proposed that they start at `v3` to avoid confusion with long-standing implementations. -Servers which are lucky enough exist during this versioning scheme change are expected to continue +Servers which are lucky enough to exist during this versioning scheme change are expected to continue supporting the `rN` system. This is done by advertising the existing client-server API versions as they always would have on `/versions`, though appending `"v1.1.0"` to indicate that this MSC is supported. -As a further clarification to an solved problem, the `/versions` endpoint for the client-server API +As a further clarification to a solved problem, the `/versions` endpoint for the client-server API does not need to advertise all patch version changes - just the major/minor versions it supports. If a server does advertise a patch version, clients are expected to resolve that to the relevant major/minor version equivalent (`v1.1.8` gets treated as `v1.1.0`, for example). @@ -245,7 +245,7 @@ and the two most recent `MINOR` versions past that. Given a cadence of about 1 r this should mean that the standard implementation supports roughly 1.5 years worth of Matrix history. Room versions are special in that they will essentially always be included in a Matrix release, even if -unstable. The current specification says that implementatiosn don't have to implement unstable room +unstable. The current specification says that implementations don't have to implement unstable room versions, and this is true under this MSC too. For extreme clarity, the suggested schedule for supported versions would be (all examples): From 09c569f1a76c4fcce148a847f9b541ae37269933 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 22 Nov 2020 01:03:54 -0700 Subject: [PATCH 07/14] Cover a case of no-op versions --- proposals/2844-global-versioning.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 0204c5e4..f4cbf026 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -248,13 +248,20 @@ Room versions are special in that they will essentially always be included in a unstable. The current specification says that implementations don't have to implement unstable room versions, and this is true under this MSC too. +As with the current day, implementations should consider what makes sense for them to support. It's +entirely possible that a Matrix version happens with no client-server API changes, for instance, which +may mean that clients won't bother even checking for the no-op version - a server implementation might +not want to count that version towards it's "last 2 major releases" schedule to avoid breaking clients. +It may instead be desirable for implementations to support Matrix releases based on time rather than +by the number of releases. + For extreme clarity, the suggested schedule for supported versions would be (all examples): -* v1.1.0 - Released in January 2019 - No support needed due to age. -* v1.2.0 - Released in July 2019 - Should be supported as part of the 1.2.x series. -* v1.2.5 - Released in August 2019 - Should be supported because it's part of the 1.2.x series. -* v1.3.0 - Released in December 2019 - Should be supported. -* v1.4.0 - Released in January 2020 - The current release so should definitely be supported. +* v1.1.0 - Released in January - No support needed due to age. +* v1.2.0 - Released in July - Should be supported as part of the 1.2.x series. +* v1.2.5 - Released in August - Should be supported because it's part of the 1.2.x series. +* v1.3.0 - Released in November - Should be supported. +* v1.4.0 - Released in December (current day) - The current release so should definitely be supported. ## Potential issues From 8cc3d44c2ac32d7cd6b657df622d46c66b3581d2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 22 Nov 2020 01:22:05 -0700 Subject: [PATCH 08/14] Generally wording changes; Change deprecation --- proposals/2844-global-versioning.md | 33 +++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index f4cbf026..2ed54420 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -214,11 +214,15 @@ been deprecated for suitably long enough, it is eligible for removal from the sp MSC. Today's process is the same, though not defined explicitly. Also not mentioned in today's system is that implementations are not required to implement deprecated -endpoints. This MSC also changes that and says that they do for versions in which they were deprecated -in. For example, if an endpoint was introduced in v1.1, deprecated in v1.2, and removed in v1.3 then -a server would have to implement the endpoint for v1.1 and v1.2 if it wanted to claim support for those -versions - v1.3 doesn't have the endpoint, so the endpoint's existence is not conditional for being -able to claim support for that version. +endpoints. This MSC doesn't change that, but does put some rules around how deprecation works for a +given endpoint. Specifically, if a server wants to support a Matrix version where an endpoint is *not* +deprecated, then it must serve it. + +As an example, if `/test` were introduced in v1.1, deprecated in v1.2, and removed in v1.3 then an +implementation can support v1.1, v1.2, and v1.3 by implementing `/test` as it was defined in v1.2 (minus +the deprecation flag). If the implementation wanted to support just v1.2 and v1.3, then it could +optionally implement `/test`, though is encouraged to. Further, if the implementation only wanted to +support v1.3, then it *should not* implement `/test` at all because it was removed. Generally deprecation is paired with replacement or breaking changes. For example, if `/v3/sync` were to be modified such that it needed to be bumped to `v4`, the MSC which does so would deprecate `/v3/sync` @@ -301,6 +305,13 @@ instead of the inspired system proposed here. So, why shouldn't we use semantic 4. The benefit of saying we use a well-popularized versioning system is not a strong enough argument to be considered here. +This MSC is also inherently incompatible with semantic versioning due to its approach to deprecation. +Instead of encouraging breaking changes (removal of endpoints) be major version changes, this MSC +says that happens at the minor version change level. As mentioned in the relevant section, this is +not foreseen to be an issue for Matrix given its a system already used by the protocol and is common +enough to at least be moderately familiar - the arguments for using semantic versioning in this respect +do not hold up, per above. + ## Security considerations None relevant - if we need to make a security release for Matrix then we simply make a release and @@ -308,7 +319,11 @@ 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`. +The author does not recommend that this MSC be implemented prior to it landing due to the complexity +involved as well as the behavioural changes not being possible to implement. However, if an implementation +wishes to try anyways, it should use `org.matrix.msc2844` in the `unstable_features` of `/versions` +and use `/_matrix/client/unstable/org.matrix.msc2844` in place of `/_matrix/client/r0`. + +This MSC is largely proven as possible through an in-development build of the specification which uses +an alternative toolchain for rendering the specification: https://adoring-einstein-5ea514.netlify.app/ +(see the 'releases' dropdown in the top right; link may not be available in the distant future - sorry). From 11daaf6ea93304271e0c62265a32072d5765f46a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 22 Nov 2020 18:58:36 -0700 Subject: [PATCH 09/14] Add a small note about widgets --- proposals/2844-global-versioning.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 2ed54420..8b309731 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -121,7 +121,10 @@ supported. As a further clarification to a solved problem, the `/versions` endpoint for the client-server API does not need to advertise all patch version changes - just the major/minor versions it supports. If a server does advertise a patch version, clients are expected to resolve that to the relevant -major/minor version equivalent (`v1.1.8` gets treated as `v1.1.0`, for example). +major/minor version equivalent (`v1.1.8` gets treated as `v1.1.0`, for example). This same rule +applies to widgets and the `supported_api_versions` action, which is currently in a +[draft specification](https://github.com/matrix-org/matrix-doc/pull/2764) state. Once widgets land +in the spec, the rule comes into effect. ### Brewing changes for the specification From b07618cc3f4096dbf6cdbe53ae54f36fbf826598 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 15 Dec 2020 09:49:27 -0700 Subject: [PATCH 10/14] Make clarifications to the spec --- proposals/2844-global-versioning.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 8b309731..43723142 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -7,7 +7,7 @@ which apply: 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 +3. Room versions which define 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 @@ -29,9 +29,9 @@ it currently), the APIs, room versions, and the appendices (which are also curre contain specification). Room versions are a bit more nuanced though, and are covered later in this MSC. The version which covers the entire specification and all its parts is called the "Matrix version", and -is a promotion of the previously marketing-only version number assigned to the spec. Upon acceptance of -this MSC, the Matrix version would be 1.1.0. v1.0 from the marketing era would be recorded somewhere for -posterity, though largely has no significant meaning (unchanged by this MSC). +is a promotion of the previously marketing-only version number assigned to the spec. The spec core team +is expected to release Matrix 1.1.0 as the first version, leaving v1.0 as the marketing era and recorded +somewhere for posterity (though has no significant meaning, unchanged by this MSC). Doing this has the benefits previously alluded to: @@ -66,10 +66,10 @@ Given a version number `MAJOR.MINOR.PATCH`, incremement the: When present in the protocol itself, the Matrix version will always be prefixed with `v`. For example, `v1.1.0`. -When a dash (`-`) is present after the `PATCH` version, the version is denoting some off-cycle release -information. This is how we'd, for example, make release candidates, alpha, beta, or unstable builds as -needed. This MSC does not propose a scheme for RCs or pre-releases, though the Spec Core Team may wish -to do so. +Additional information can be supplied in the version number by appending a dash (`-`) to the end of the +version and including any relevant information. This is typically used to denote alpha, beta, unstable, +or other similar off-cycle release builds. This MSC does not propose a scheme for RCs or pre-releases, +though the Spec Core Team may wish to do so. See the section on brewing Matrix versions for information on how the unstable version is decided. @@ -158,7 +158,7 @@ the Spec Core Team be able to blindside the community with a release for no just To recap, the process is as follows: -1. Sometime after a given release happens, the Spec Core Team announces a cutoff date for MSCs to land +1. Sometime before a given release happens, the Spec Core Team announces a cutoff date for MSCs to land that is at least 2 months in the future. 2. Upon cutoff, the Spec Core Team takes responsibility for ensuring all relevant changes are written up in a timely fashion. From 7b4e702a699208678332b40db9caf45098192598 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 9 Jan 2021 20:33:20 -0700 Subject: [PATCH 11/14] Remove patch versions, policy stuff, etc --- proposals/2844-global-versioning.md | 165 +++++----------------------- 1 file changed, 25 insertions(+), 140 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 43723142..3e2ee0aa 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -6,7 +6,7 @@ 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). + endpoint, thus making most endpoints under it `/r0/` (currently). 3. Room versions which define 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 @@ -29,9 +29,10 @@ it currently), the APIs, room versions, and the appendices (which are also curre contain specification). Room versions are a bit more nuanced though, and are covered later in this MSC. The version which covers the entire specification and all its parts is called the "Matrix version", and -is a promotion of the previously marketing-only version number assigned to the spec. The spec core team -is expected to release Matrix 1.1.0 as the first version, leaving v1.0 as the marketing era and recorded -somewhere for posterity (though has no significant meaning, unchanged by this MSC). +is a promotion of the previously marketing-only version number assigned to the spec. The first version +after this proposal is expected to be Matrix 1.1, though the spec core team will make that distinction. +v1.0 would be left in the marketing era and recorded for posterity (though still retains no significant +meaning). Doing this has the benefits previously alluded to: @@ -52,7 +53,7 @@ The Matrix versioning scheme takes heavy inspiration from semantic versioning, t not follow it for reasons described throughout this proposal. Primarily, the argument against semantic versioning is held in the alternatives section below. -Given a version number `MAJOR.MINOR.PATCH`, incremement the: +Given a version number `MAJOR.MINOR`, incremement the: * `MAJOR` version when a substantial change is made to the core of the protocol. This is reserved for interpretation by the Spec Core Team, though is intended to be for extremely invasive changes such @@ -60,33 +61,28 @@ Given a version number `MAJOR.MINOR.PATCH`, incremement the: doesn't feel good enough, or changes to the signing algorithms. * `MINOR` version when a feature is introduced, or a backwards incompatible change has been managed through the specification. Later on, this proposal explains what it means to manage a breaking change. -* `PATCH` version when correctional changes are made, such as spelling, cosmetic, or other similarly - small patches are done. Implementations do not need to worry about the patch version. When present in the protocol itself, the Matrix version will always be prefixed with `v`. For example, -`v1.1.0`. +`v1.1`. Additional information can be supplied in the version number by appending a dash (`-`) to the end of the version and including any relevant information. This is typically used to denote alpha, beta, unstable, or other similar off-cycle release builds. This MSC does not propose a scheme for RCs or pre-releases, -though the Spec Core Team may wish to do so. +though the Spec Core Team may wish to do so. This can also be used to represent patch builds for the +documentation itself, such as correcting spelling mistakes. An example would be `v1.1-patch.20210109`. See the section on brewing Matrix versions for information on how the unstable version is decided. -From an implementation perspective, compatibility is guaranteed between `PATCH` versions. `MINOR` versions -have a backwards compatibility scheme described later in this proposal. `MAJOR` versions are expected -to have zero backwards compatibility guarantees to them. +`MINOR` versions have a backwards compatibility scheme described later in this proposal. `MAJOR` +versions are expected to have zero backwards compatibility guarantees to them. -For clarity, `v1.1.0` and `v1.1.8` are functionally the same. `v1.2.0` will probably work with `v1.1.0`, -though implementations should be wary if they depend on a version. As mentioned, the backwards compatibility -scheme section goes into more detail on this. +For clarity, `v1.2.0` will probably work with `v1.1.0`, though implementations should be wary if they +depend on a version. As mentioned, the backwards compatibility scheme section goes into more detail on +this. -A potential argument is that we don't need a patch version if no implementation will ever care about it, -which is a valid argument to have. This MSC believes that although the patch version is effectively useless -to implementations, it is valuable as evidence of progress and finality of a given version. Going back to -edit already-released versions of the specification can be damaging to the integrity of the protocol, -and thus it is proposed by this MSC that the Spec Core Team remain accountable by forcing them to release -with a patch version increase for minor, functionally indifferent, changes. +Most notably, this MSC does not propose including a patch version at all. The specifics of what would +be included in a patch version (spelling changes, release process bug fixes, etc) do not impact any +implementations of Matrix and thus are not needing of a patch version. ### Structure changes and changelogs @@ -95,16 +91,10 @@ but won't have versions associated with those particular documents. This also me individual changelogs in favour of a more general changelog. An exception to this rule is room versions, which are covered later in this proposal. -Though the changelog format is not covered by the MSC process, this MSC proposes that the initial -changelog for the Matrix versioning scheme be broken out into sections for each API that had changes. -Ideally, the changelog would also indicate if no changes were made to a particular API/area to help -be clearer to implementation authors. The Push Gateway API is, for example, likely going to be one -of the few which will nearly always say "No relevant changes" for years. - ### Endpoint versioning Under this MSC, all HTTP endpoints in the specification are to be per-endpoint versioned. This is already -the case for all APIs except the client-server API, and so this section deals specifically with that API. +the case for all APIs except the Client-Server API, and so this section deals specifically with that API. The deprecation of endpoints is handled later in this proposal. Under this proposal, all endpoints in the client-server API get assigned `v3` as their per-endpoint @@ -113,67 +103,11 @@ versions which had `v1` and called the `rN` system "v2". Though many of the endp are not present in those older API editions, it is still proposed that they start at `v3` to avoid confusion with long-standing implementations. -Servers which are lucky enough to exist during this versioning scheme change are expected to continue -supporting the `rN` system. This is done by advertising the existing client-server API versions as -they always would have on `/versions`, though appending `"v1.1.0"` to indicate that this MSC is -supported. - -As a further clarification to a solved problem, the `/versions` endpoint for the client-server API -does not need to advertise all patch version changes - just the major/minor versions it supports. -If a server does advertise a patch version, clients are expected to resolve that to the relevant -major/minor version equivalent (`v1.1.8` gets treated as `v1.1.0`, for example). This same rule -applies to widgets and the `supported_api_versions` action, which is currently in a -[draft specification](https://github.com/matrix-org/matrix-doc/pull/2764) state. Once widgets land -in the spec, the rule comes into effect. - -### Brewing changes for the specification - -Prior to this MSC, the Spec Core Team would release a given version of an API whenever it felt like -the right time to do so. There's very little planning put into a release, and often times the call to -cut a release is arbitrary. Though this MSC doesn't solve this problem neccesarily, it does change -the dynamic the Spec Core Team has with the community when it comes to releases. - -Instead of arbitrarily deciding when to cut a release, the Spec Core Team is expected to plan ahead -and choose a date for the next major/minor release. The team is not required to use a cadence to -perform releases, though is expected to perform at least one release a year. Reasonable notice is -expected to be given to the community to give them a chance to push their MSCs and ideas to -completion. "Reasonable" is intentionally left undefined by this MSC as it might change over time, -though the current suggestion is to give at least 2 months notice. Most MSC authors are currently -contributing on a volunteer or spare time basis and thus might not be able to rapidly push their -ideas through the stages as quickly. - -Patch releases do not require such notice and can happen whenever. - -The date advertised to the community is a cutoff date, not a release date. The Spec Core Team and -wider community might still need time to write up the formal specification for some MSCs or improve -their implementations to be more prepared for the impending official release. In the eyes of the MSC -process, the cutoff date is *not* enough for an implementation to switch to using stable endpoints. - -Considering these are only expectations and not requirements, the Spec Core Team might break them -from time to time for various reasons including urgent security releases, last minute realizations -that something might not work as proposed, etc. Under the Foundation, the Spec Core Team is required -to act in the best interest of the protocol and therefore should be able to reasonably justify why -an expectation is being broken at the time of breaking it - in no way does this MSC propose that -the Spec Core Team be able to blindside the community with a release for no justifiable reason. - -To recap, the process is as follows: - -1. Sometime before a given release happens, the Spec Core Team announces a cutoff date for MSCs to land - that is at least 2 months in the future. -2. Upon cutoff, the Spec Core Team takes responsibility for ensuring all relevant changes are written - up in a timely fashion. -3. The Spec Core Team makes the release. At this point, implementations can stop using unstable - prefixes for any included MSC. - -Because the release schedule is well-advertised, it should be clear to everyone what the next non-patch -version number will be. By default, the assumption can be made that the `MINOR` version will increase -by 1. For the purposes of producing built copies of the spec, the version number for unstable (unreleased) -versions shall be the next *expected* version number followed by `-unstable`. For example, if `v1.1.0` -were the current release, the unstable specification would be built as `v1.2.0-unstable`. In the event -that a change lands where the major version needs incremementing, `v1.2.0` (in this example) would never -see the light of day and instead turn into `v2.0.0-unstable`. - -### Room versions & brewing room versions +Servers would advertise support for the new Matrix version by appending it to the array in `/versions`. +If the sever also supports an older `rN` version, it would include those too. +For example: `["v1.1", "r0.6.1"]`. + +### Room versions *Author's note*: Having many things with the root word "version" can be confusing, so for this section "room versions" are called "room editions" and the Matrix version refers to what this proposal is @@ -188,26 +122,6 @@ Whenever a room edition transitions from stable to unstable, or unstable to stab then it would get counted as a feature for a `MINOR` release of Matrix. We don't currently have a plan to remove any room editions, so they are not covered as a potential process for this MSC. -The brewing process for a room edition has typically been a last minute MSC to declare an edition number -and which other MSCs are included. This MSC proposes changing that slightly to instead allow accepted -MSCs to be batched up at release time into a new room edition. Each MSC will have needed testing and -implementation validation prior to their acceptance, so it should be fine to merge them together. If -a concern or conflict were to arise about doing so, an explicit MSC could be raised just like in today's -model where the conflicts/concerns are resolved. Such concerns might be the compatibility of the features, -and some conflicts might be two MSCs changing the same authorization rule (for example). The new, explicit, -MSC would require implementation validation and testing to be approved and thus would then be fine. - -Though somewhat implicit, it might not be clear: multiple room editions can be included in a single Matrix -release, though how they get built is not really addressed by this MSC. Using the spirit of the ideas -proposed, it would likely mean as many MSCs as room editions to bring them into effect. This sort of -practice is believed to be extremely rare, however - it'd be more likely that the Spec Core Team uses -their capability to do an emergency release of Matrix to get a room edition into the wild rather than -brew two (or more) room editions at once. - -The recommended default room edition is not automatically changed under this proposal either - changing -the recommended default requires an MSC just like any other part of Matrix and would fall under general -feature changes. - ### Deprecation approach This MSC doesn't change much about how things get deprecated, though it would be codified by this MSC. @@ -240,36 +154,6 @@ or outright remove the endpoint, however the Matrix specification tends to have associated with it and thus means we should support a larger than average backwards compatibility period. -### Supported versions schedule - -Currently implementations are left to fend for themselves on deciding which versions of their APIs to -support. This MSC doesn't change this due to a wide variety of potential use cases for different -environments and older specifications, though this MSC does bring forth a guiding principle which is -applicable to most standard implementations. - -Implementations are encouraged to support the latest version of Matrix as soon as feasibly possible, -and the two most recent `MINOR` versions past that. Given a cadence of about 1 release every 6 months, -this should mean that the standard implementation supports roughly 1.5 years worth of Matrix history. - -Room versions are special in that they will essentially always be included in a Matrix release, even if -unstable. The current specification says that implementations don't have to implement unstable room -versions, and this is true under this MSC too. - -As with the current day, implementations should consider what makes sense for them to support. It's -entirely possible that a Matrix version happens with no client-server API changes, for instance, which -may mean that clients won't bother even checking for the no-op version - a server implementation might -not want to count that version towards it's "last 2 major releases" schedule to avoid breaking clients. -It may instead be desirable for implementations to support Matrix releases based on time rather than -by the number of releases. - -For extreme clarity, the suggested schedule for supported versions would be (all examples): - -* v1.1.0 - Released in January - No support needed due to age. -* v1.2.0 - Released in July - Should be supported as part of the 1.2.x series. -* v1.2.5 - Released in August - Should be supported because it's part of the 1.2.x series. -* v1.3.0 - Released in November - Should be supported. -* v1.4.0 - Released in December (current day) - The current release so should definitely be supported. - ## Potential issues None appear to be relevant to be discussed on their own - they are discussed in their respective @@ -329,4 +213,5 @@ and use `/_matrix/client/unstable/org.matrix.msc2844` in place of `/_matrix/clie This MSC is largely proven as possible through an in-development build of the specification which uses an alternative toolchain for rendering the specification: https://adoring-einstein-5ea514.netlify.app/ -(see the 'releases' dropdown in the top right; link may not be available in the distant future - sorry). +(see the 'releases' dropdown in the top right; link may not be available or even the same as described +here due to development changes - sorry). From 22acbea0ed9c02eec321517191bc0dff411931e0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 9 Jan 2021 20:38:58 -0700 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Kitsune Ral --- proposals/2844-global-versioning.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 3e2ee0aa..431d85b1 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -113,10 +113,10 @@ For example: `["v1.1", "r0.6.1"]`. "room versions" are called "room editions" and the Matrix version refers to what this proposal is introducing. This MSC does not propose renaming "room versions" - that is another MSC's problem. -Room editions are a bit special in that they have their own versioning scheme as other servers need to -be aware of how to process the room. As such, a room edition's versioning scheme is not altered by this -proposal, however the publishing of the (in)stability of a given edition is now covered by the newly -proposed Matrix version. +Room editions are a bit special in that they have their own versioning scheme as servers and, potentially, +clients need to be aware of how to process the room. As such, a room edition's versioning scheme is not +altered by this proposal, however the publishing of the (in)stability of a given edition is now covered by the +newly proposed Matrix version. Whenever a room edition transitions from stable to unstable, or unstable to stable, or is introduced then it would get counted as a feature for a `MINOR` release of Matrix. We don't currently have a plan From 124c8d43d3491042b330ab4806c7b542af861831 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Jan 2021 09:22:06 -0700 Subject: [PATCH 13/14] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2844-global-versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 431d85b1..0f2d4c66 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -30,7 +30,7 @@ contain specification). Room versions are a bit more nuanced though, and are cov The version which covers the entire specification and all its parts is called the "Matrix version", and is a promotion of the previously marketing-only version number assigned to the spec. The first version -after this proposal is expected to be Matrix 1.1, though the spec core team will make that distinction. +after this proposal is expected to be Matrix 1.1, though the spec core team will make that decision. v1.0 would be left in the marketing era and recorded for posterity (though still retains no significant meaning). @@ -76,7 +76,7 @@ See the section on brewing Matrix versions for information on how the unstable v `MINOR` versions have a backwards compatibility scheme described later in this proposal. `MAJOR` versions are expected to have zero backwards compatibility guarantees to them. -For clarity, `v1.2.0` will probably work with `v1.1.0`, though implementations should be wary if they +For clarity, `v1.2` will probably work with `v1.1`, though implementations should be wary if they depend on a version. As mentioned, the backwards compatibility scheme section goes into more detail on this. From 46d843e8fa7ec3b8e3e5d48ff2e4bd72bbcb1127 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Jan 2021 09:52:36 -0700 Subject: [PATCH 14/14] Make deprecation industry standard --- proposals/2844-global-versioning.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 0f2d4c66..b6db20c1 100644 --- a/proposals/2844-global-versioning.md +++ b/proposals/2844-global-versioning.md @@ -124,22 +124,23 @@ to remove any room editions, so they are not covered as a potential process for ### Deprecation approach -This MSC doesn't change much about how things get deprecated, though it would be codified by this MSC. +Previous to this proposal the deprecation approach was largely undocumented - this MSC aims to codify +a standardized approach. An MSC is required to transition something from stable (the default) to deprecated. Once something has -been deprecated for suitably long enough, it is eligible for removal from the specification with another -MSC. Today's process is the same, though not defined explicitly. +been deprecated for suitably long enough (usually 1 version), it is eligible for removal from the +specification with another MSC. Today's process is the same, though not defined explicitly. -Also not mentioned in today's system is that implementations are not required to implement deprecated -endpoints. This MSC doesn't change that, but does put some rules around how deprecation works for a -given endpoint. Specifically, if a server wants to support a Matrix version where an endpoint is *not* -deprecated, then it must serve it. +The present system for deprecation also allows implementations to skip implementation of deprecated +endpoints. This proposal does not permit such behaviour: for an implementation to remain compliant +with the specification, it must implement all endpoints (including deprecated ones) in the version(s) +it wishes to target. As an example, if `/test` were introduced in v1.1, deprecated in v1.2, and removed in v1.3 then an implementation can support v1.1, v1.2, and v1.3 by implementing `/test` as it was defined in v1.2 (minus -the deprecation flag). If the implementation wanted to support just v1.2 and v1.3, then it could -optionally implement `/test`, though is encouraged to. Further, if the implementation only wanted to -support v1.3, then it *should not* implement `/test` at all because it was removed. +the deprecation flag). If the implementation wanted to support just v1.2 and v1.3, then it still must +implement `/test`. If the implementation only wanted to support v1.3, then it *should not* implement +`/test` at all because it was removed. Generally deprecation is paired with replacement or breaking changes. For example, if `/v3/sync` were to be modified such that it needed to be bumped to `v4`, the MSC which does so would deprecate `/v3/sync` @@ -147,13 +148,6 @@ in favour of its proposed `/v4/sync`. Because endpoints are versioned on a per-e will still work with a server that supports `/v3/profile` (for example) - the version number doesn't mean an implementation can only use v4 endpoints. -This sort of approach could be potentially confusing and non-standard as it would mean for an amount of -time in the specification there would be two versions of an endpoint: one deprecated and one not. Most -specifications and protocols do not use this sort of approach and instead opt to replace the whole API -or outright remove the endpoint, however the Matrix specification tends to have a longer-lived cycle -associated with it and thus means we should support a larger than average backwards compatibility -period. - ## Potential issues None appear to be relevant to be discussed on their own - they are discussed in their respective