diff --git a/README.md b/README.md index 47435d6a..ff6d932f 100644 --- a/README.md +++ b/README.md @@ -184,19 +184,94 @@ like help with writing spec PRs, feel free to join and ask questions in the #### Unstable prefixes -*Unstable* prefixes are the namespaces which are used before an MSC has -completed FCP (see above). While the MSC might propose that a `m.space` or -`/_matrix/client/v1/account/whoami` endpoint should exist, the implementation -cannot use a *stable* identifier such as `/v1/` or `m.space` prior to the MSC -being accepted: it needs unstable prefixes. - -Typically for MSCs, one will use `org.matrix.msc0000` (using the real MSC -number once known) as a prefix. For the above examples, this would mean -`org.matrix.msc0000.space` and -`/_matrix/client/unstable/org.matrix.msc0000/account/whoami` to allow for -breaking compatibility changes between edits of the MSC itself, or indeed -another competing MSC that's attempting to add the same identifiers. - +"Unstable prefixes" are the namespaces which are used by implementations while +an MSC is not yet accepted. + +For instance, an MSC might propose that a `m.space` +event type or an `/_matrix/client/v1/account/whoami` endpoint should exist. +However, implementations cannot use these *stable* identifiers until the MSC +has been accepted, as the underlying design may change at any time; the design is +*unstable*. + +Instead, an MSC can define a namespace such as `org.matrix.msc1234` (using the real +MSC number once known) which is added to the stable identifier, allowing for +breaking changes between edits of the MSC itself, and preventing clashes with other +MSCs that might attempt to add the same stable identifiers. + +For the above examples, this would mean using `org.matrix.msc1234.space` and +`/_matrix/client/unstable/org.matrix.msc1234/account/whoami`. It is also fine to +use more traditional forms of namespace prefixes, such as `com.example.*` (e.g. +`com.example.space`). + +Note: not all MSCs need to make use of unstable prefixes. They are only needed if +implementations of your MSC need to exist in the wild before your MSC is accepted, +*and* the MSC defines new endpoints, field names, etc. + +#### Unstable feature flags + +It is common when implementing support for an MSC that a client may wish to check +if the homeserver it is communicating with supports an MSC. +Typically, this is handled by the MSC defining an +entry in the `unstable_features` dictionary of the +[`/_matrix/client/versions`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientversions) +endpoint, in the form of a new entry: + +```json5 +{ + "unstable_features": { + "org.matrix.msc1234": true + } +} +``` + +... with a value of `true` indicating that the feature is supported, and `false` +or lack of the field altogether indicating the feature is not supported. + +#### When can I use stable identifiers? + +[According to the spec +process](https://spec.matrix.org/proposals/#early-release-of-an-mscidea): once +an MSC has been accepted, implementations are allowed to switch to *stable* +identifiers. However, the MSC is still not yet part of a released spec version. + +In most cases, this is not an issue. For instance, if your MSC specifies a new +event type, you can now start sending events with those types! + +Some MSCs introduce functionality where coordination between implementations is +needed. For instance, a client may want to know whether a homeserver supports +the stable version of a new endpoint before actually attempting to request it. +Or perhaps the new event type you're trying to send relies on the homeserver +recognising that new event type, and doing some work when it sees it. + +At this point, it may be best to wait until a new spec version is released with +your changes. Homeservers that support the changes will eventually advertise +that spec version under `/versions`, and your client can check for that. + +But if you really can't wait, then there is another option: the homeserver can +tell clients that it supports *stable* indentifiers for your MSC before it +enters a spec version, using yet another `unstable_features` flag: + +```json5 +{ + "unstable_features": { + "org.matrix.msc1234": true, + "org.matrix.msc1234.stable": true + } +} +``` + +If a client sees that `org.matrix.msc1234.stable` is `true`, it knows that it +can start using stable identifiers for the new MSC, and the homeserver will +accept and act on them accordingly. + +Note: While the general pattern of using the text ".stable" has emerged from +previous MSCs, you can pick any name you like. You need only to clearly state +their meaning, usually under an "Unstable prefixes" header in your MSC. + +See +[MSC3827](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3827-space-explore.md#unstable-prefix) +for a good example of an MSC that wanted to use such a flag to speed up +implementation rollout, and how it did so. #### Room versions