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