diff --git a/proposals/2844-global-versioning.md b/proposals/2844-global-versioning.md index 6eba7d0c8..a3428cfc8 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