Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-01-04 15:03:43 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Make deprecation industry standard

Browse source
This commit is contained in:
Travis Ralston 2021-01-12 09:52:36 -07:00
parent 124c8d43d3
commit 46d843e8fa
1 changed files with 11 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
proposals/2844-global-versioning.md
View file

@ -124,22 +124,23 @@ to remove any room editions, so they are not covered as a potential process for
### Deprecation approach
This MSC doesn't change much about how things get deprecated, though it would be codified by this MSC.
Previous to this proposal the deprecation approach was largely undocumented - this MSC aims to codify
a standardized approach.
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.
been deprecated for suitably long enough (usually 1 version), 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 doesn't change that, but does put some rules around how deprecation works for a
given endpoint. Specifically, if a server wants to support a Matrix version where an endpoint is *not*
deprecated, then it must serve it.
The present system for deprecation also allows implementations to skip implementation of deprecated
endpoints. This proposal does not permit such behaviour: for an implementation to remain compliant
with the specification, it must implement all endpoints (including deprecated ones) in the version(s)
it wishes to target.
As an example, if `/test` were introduced in v1.1, deprecated in v1.2, and removed in v1.3 then an
implementation can support v1.1, v1.2, and v1.3 by implementing `/test` as it was defined in v1.2 (minus
the deprecation flag). If the implementation wanted to support just v1.2 and v1.3, then it could
optionally implement `/test`, though is encouraged to. Further, if the implementation only wanted to
support v1.3, then it *should not* implement `/test` at all because it was removed.
the deprecation flag). If the implementation wanted to support just v1.2 and v1.3, then it still must
implement `/test`. If the implementation only wanted to support v1.3, then it *should not* implement
`/test` at all because it was removed.
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`
@ -147,13 +148,6 @@ in favour of its proposed `/v4/sync`. Because endpoints are versioned on a per-e
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.
This sort of approach could be potentially confusing and non-standard as it would mean for an amount of
time in the specification there would be two versions of an endpoint: one deprecated and one not. Most
specifications and protocols do not use this sort of approach and instead opt to replace the whole API
or outright remove the endpoint, however the Matrix specification tends to have a longer-lived cycle
associated with it and thus means we should support a larger than average backwards compatibility
period.
## Potential issues
None appear to be relevant to be discussed on their own - they are discussed in their respective