From 1310c7c8bf4aff233d0c44bdb51181c61d77aa88 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 12 Nov 2020 17:45:26 -0700 Subject: [PATCH] Finish up the last few sections --- proposals/2844-global-versioning.md | 118 +++++++++++++++++++++++++--- 1 file changed, 106 insertions(+), 12 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. +*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. -**TODO: Brewing mechanics of room versions** +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. +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? -- semver +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