Clarify how to make use of unstable prefixes in your MSC

README.md

@@ -182,21 +182,95 @@ like help with writing spec PRs, feel free to join and ask questions in the
 
 ### Other useful information
 
-#### 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.
-
+#### Stable and unstable prefixes
+
+*Unstable* prefixes are the namespaces which are used by implementations while
+an MSC is not yet accepted. For instance, an MSC can propose that a `m.space`
+event type or an `/_matrix/client/v1/account/whoami` endpoint should exist.
+However, an implementation of that same MSC cannot use a *stable* prefix (in the
+case, `/_matrix/client/` or `m.`) until the MSC has been accepted, as the
+underlying design may change at any time; the design is
+*unstable*.
+
+Typically MSCs will define `org.matrix.msc1234` (using the real MSC number once
+known) as an *unstable* prefix. For the above examples, this would mean using
+`org.matrix.msc1234.space` and
+`/_matrix/client/unstable/org.matrix.msc1234/account/whoami` to allow for
+breaking changes between edits of the MSC itself, or to not clash with another
+MSC that's attempting to add the same stable identifiers. The unstable
+prefixes, in this case, are `org.matrix.msc1234` and `/_matrix/client/unstable`
+respectively. 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
+when defining new endpoints, field names, etc. in your MSC, and serve to allow
+implementations of your MSC to exist in the wild before your MSC is accepted.
+
+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 prefixes?
+
+[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*
+prefixes (i.e. `m.`). 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.
+
+This is often solved by having the homeserver tell clients that it supports
+stable prefixes, 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 prefixes, and the homeserver will accept and act on
+them accordingly.
+
+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 udner 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