Remove patch versions, policy stuff, etc

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