Finish up the last few sections

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