archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Describe new global specification versioning (#3420)

Browse Source 
* Update versioning specification for Matrix

As per [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844)

* Mention vX versioning in /versions

* Changelog
pull/977/head
Travis Ralston 3 years ago committed by GitHub
parent 2fc3982568
commit 2d98cd3084
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 78 additions and 39 deletions
Show Stats Download Patch File Download Diff File

1
changelogs/client_server/newsfragments/3420.clarification
Unescape Escape View File

@ -0,0 +1 @@
Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint.

107
content/_index.md
Unescape Escape View File

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

9
data/api/client-server/versions.yaml
Unescape Escape View File

@ -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
}

Write Preview
Loading…
Cancel
Save