From 2d98cd3084788ec4a1b8befa4fc15c7f89e00efe Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Oct 2021 11:06:51 -0600 Subject: [PATCH] Describe new global specification versioning (#3420) * Update versioning specification for Matrix As per [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) * Mention vX versioning in /versions * Changelog --- .../newsfragments/3420.clarification | 1 + content/_index.md | 107 ++++++++++++------ data/api/client-server/versions.yaml | 9 +- 3 files changed, 78 insertions(+), 39 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3420.clarification diff --git a/changelogs/client_server/newsfragments/3420.clarification b/changelogs/client_server/newsfragments/3420.clarification new file mode 100644 index 00000000..fd838ff6 --- /dev/null +++ b/changelogs/client_server/newsfragments/3420.clarification @@ -0,0 +1 @@ +Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. diff --git a/content/_index.md b/content/_index.md index 73bcd3af..c7d0acda 100644 --- a/content/_index.md +++ b/content/_index.md @@ -37,28 +37,6 @@ The [Matrix Client-Server API Swagger Viewer](https://matrix.org/docs/api/client-server/) is useful for browsing the Client-Server API. -### Matrix versions - -{{% boxes/note %}} -As of June 10th 2019, the Matrix specification is considered out of beta -- indicating that all currently released APIs are considered stable and -secure to the best of our knowledge, and the spec should contain the -complete information necessary to develop production-grade -implementations of Matrix without the need for external reference. -{{% /boxes/note %}} - -Matrix 1.0 (released June 10th, 2019) consists of the following minimum -API versions: - -| API/Specification | Version | -|-------------------------|---------| -| Client-Server API | r0.5.0 | -| Server-Server API | r0.1.2 | -| Application Service API | r0.1.1 | -| Identity Service API | r0.1.1 | -| Push Gateway API | r0.1.0 | -| Room Version | v5 | - ## Introduction to the Matrix APIs Matrix is a set of open APIs for open-federated Instant Messaging (IM), @@ -526,18 +504,79 @@ The available room versions are: ## Specification Versions -The specification for each API is versioned in the form `rX.Y.Z`. -- A change to `X` reflects a breaking change: a client implemented - against `r1.0.0` may need changes to work with a server which - supports (only) `r2.0.0`. -- A change to `Y` represents a change which is backwards-compatible - for existing clients, but not necessarily existing servers: a client - implemented against `r1.1.0` will work without changes against a - server which supports `r1.2.0`; but a client which requires `r1.2.0` - may not work correctly with a server which implements only `r1.1.0`. -- A change to `Z` represents a change which is backwards-compatible on - both sides. Typically this implies a clarification to the - specification, rather than a change which must be implemented. +Matrix as a whole is released under a single specification number in the +form `vX.Y`. + +* A change to `X` reflects a breaking or substantially invasive change. + When exactly to increment this number is left to the Spec Core Team, + however it is intended for changes such as moving away from JSON, + altering the signing algorithm, or when a large number of `Y` changes + feel deserving of a major version increase. +* A change to `Y` represents a backwards compatible or "managed" backwards + compatible change to the specification, usually in the form of features. + +Additionally, the spec version may have arbitrary metadata applied to it +when followed by a `-`. For example, `v1.1-alpha`. Usage of this is not +strictly specified but is intended for usage of pre-release builds of the +specification. + +Note that while `v1.2` is meant to be backwards compatible with `v1.1`, it +is not guaranteed that future versions will be fully backwards compatible +with `v1.1`. For example, if `/test` were to be introduced in `v1.1` and +deprecated in `v1.2`, then it can be removed in `v1.3`. More information +about this is described in the [deprecation policy](#deprecation-policy) +below. + +### Endpoint versioning + +All API endpoints within the specification are versioned individually. +This means that `/v3/sync` (for example) can get deprecated in favour +of `/v4/sync` without affecting `/v3/profile` at all. A server supporting +`/v4/sync` would keep serving `/v3/profile` as it always has. + +When an MSC proposes a breaking change to an endpoint it should also +deprecate the existing endpoint. For some endpoints this might be implicit, +such as `/v4/sync` being introduced (deprecating `/v3/sync`), however +for more nuanced examples the MSC should deprecate the endpoint explicitly. + +### Deprecation policy + +An MSC is required to transition something from stable (the default) to +deprecated. Once something has been deprecated for suitably long enough +(usually 1 version), it is eligible for removal from the specification +with another MSC. + +Implementations of Matrix are required to implement deprecated functionality +of the specification, though when the functionality is later removed then +the implementation is welcome to drop support (if they don't advertise +support for a version which includes deprecated functionality). For +example, if `/test` were deprecated in `v1.2` and removed in `v1.3`, then +an implementation which wants to advertise support for `v1.2` would have +to implement `/test`, even if the implementation also advertises support +for `v1.3`. If that implementation *only* advertises support for `v1.3` +then it would not be required to implement `/test`. + +### Legacy versioning + +Prior to this system, the different APIs of Matrix were versioned individually. +This is no longer possible with the new specification versioning approach. + +For historical reference, the APIs were versioned as `rX.Y.Z` where `X` +roughly represents a breaking change, `Y` a backwards-compatible change, and +`Z` a patch or insignificant alteration to the API. + +`v1.0` of Matrix was released on June 10th, 2019 with the following API +versions: + +| API/Specification | Version | +|-------------------------|---------| +| Client-Server API | r0.5.0 | +| Server-Server API | r0.1.2 | +| Application Service API | r0.1.1 | +| Identity Service API | r0.1.1 | +| Push Gateway API | r0.1.0 | +| Room Version | v5 | + ## License diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml index e359de3c..58c1fbe0 100644 --- a/data/api/client-server/versions.yaml +++ b/data/api/client-server/versions.yaml @@ -29,10 +29,9 @@ paths: description: |- Gets the versions of the specification supported by the server. - Values will take the form `rX.Y.Z`. - - Only the latest `Z` value will be reported for each supported `X.Y` value. - i.e. if the server implements `r0.0.0`, `r0.0.1`, and `r1.2.0`, it will report `r0.0.1` and `r1.2.0`. + Values will take the form `vX.Y` or `rX.Y.Z` in historical cases. See + [the Specification Versioning](../#specification-versions) for more + information. The server may additionally advertise experimental features it supports through `unstable_features`. These features should be namespaced and @@ -52,7 +51,7 @@ paths: description: The versions supported by the server. examples: application/json: { - "versions": ["r0.0.1"], + "versions": ["r0.0.1", "v1.1"], "unstable_features": { "org.example.my_feature": true }