@ -262,7 +262,7 @@ is as follows:
will warrant another MSC. Any minor, non-fundamental changes are
will warrant another MSC. Any minor, non-fundamental changes are
allowed but **must** be documented in the original proposal
allowed but **must** be documented in the original proposal
document. This ensures that someone reading a proposal in the future
document. This ensures that someone reading a proposal in the future
doesn't assume old information wasn't merged into the spec.
doesn't assume old information that wasn't merged into the spec.
- Similar to the proposal PR, please sign off the spec PR as per
- Similar to the proposal PR, please sign off the spec PR as per
the guidelines on
the guidelines on
[CONTRIBUTING.rst ](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst ).
[CONTRIBUTING.rst ](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst ).
@ -391,13 +391,11 @@ release, implementations are required to use the following process to
ensure that the official Matrix namespace is not cluttered with
ensure that the official Matrix namespace is not cluttered with
development or testing data.
development or testing data.
Note
**Note:** Unreleased implementations (including proofs-of-concept demonstrating
Unreleased implementations (including proofs-of-concept demonstrating
that a particular MSC works) do not have to follow this process.
that a particular MSC works) do not have to follow this process.
1. Have an idea for a feature.
1. Have an idea for a feature.
2 . Implement the feature using unstable endpoints, vendor prefixes, and
1 . Implement the feature using unstable endpoints, vendor prefixes, and
unstable feature flags as appropriate.
unstable feature flags as appropriate.
- When using unstable endpoints, they MUST include a vendor
- When using unstable endpoints, they MUST include a vendor
prefix. For example:
prefix. For example:
@ -432,22 +430,25 @@ that a particular MSC works) do not have to follow this process.
- If at any point after early release, the idea changes in a
- If at any point after early release, the idea changes in a
backwards-incompatible way, the feature flag should also change
backwards-incompatible way, the feature flag should also change
so that implementations can adapt as needed.
so that implementations can adapt as needed.
3 . In parallel, or ahead of implementation, open an MSC and solicit
1 . In parallel, or ahead of implementation, open an MSC and solicit
review per above.
review per above.
4 . Before FCP can be called, the Spec Core Team will require evidence
1 . Before FCP can be called, the Spec Core Team will require evidence
of the MSC working as proposed. A typical example of this is an
of the MSC working as proposed. A typical example of this is an
implementation of the MSC, though the implementation does not need
implementation of the MSC, though the implementation does not need
to be shipped anywhere and can therefore avoid the
to be shipped anywhere and can therefore avoid the
forwards/backwards compatibility concerns mentioned here.
forwards/backwards compatibility concerns mentioned here.
5 . The FCP process is completed, and assuming nothing is flagged the
1 . The FCP process is completed, and assuming nothing is flagged the
MSC lands.
MSC lands.
6. A spec PR is written to incorporate the changes into Matrix.
1. Implementations can now switch to using stable prefixes
7. A spec release happens.
(for example, for an endpoint, moving from
8. Implementations switch to using stable prefixes (e.g.: `/r0` ) if the
`/unstable/org.matrix.mscxxxx/frobnicate`
server supports the specification version released. If the server
to `/v1/frobnicate` ), assuming that the change
doesn't advertise the specification version, but does have the
is backwards compatible with older implementations. In the rare occasion
feature flag, unstable prefixes should still be used.
where backwards compatibility is not possible without a new spec release,
9. A transition period of about 2 months starts immediately after the
implementations should continue to use unstable prefixes.
1. A spec PR is written to incorporate the changes into Matrix.
1. A spec release happens.
1. A transition period of about 2 months starts immediately after the
spec release, before implementations start to encourage other
spec release, before implementations start to encourage other
implementations to switch to stable endpoints. For example, a server
implementations to switch to stable endpoints. For example, a server
implementation should start asking client implementations to support
implementation should start asking client implementations to support
@ -466,9 +467,9 @@ com.example/new/endpoint`.
In summary:
In summary:
- Implementations MUST NOT use stable endpoints before the MSC is in
- Implementations MUST NOT use stable endpoints before the MSC has
the spec. This includes NOT using stable endpoints in the perio d
completed FCP. Once that has occurred, implementations are allowe d
between completion of FCP and release of the spec. passed .
to use stable endpoints, but are not required to .
- Implementations are able to ship features that are exposed to users
- Implementations are able to ship features that are exposed to users
by default before an MSC has been merged to the spec, provided they
by default before an MSC has been merged to the spec, provided they
follow the process above.
follow the process above.