diff --git a/content/proposals.md b/content/proposals.md index d724f308..4a236701 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -262,7 +262,7 @@ is as follows: will warrant another MSC. Any minor, non-fundamental changes are allowed but **must** be documented in the original proposal 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 the guidelines on [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 development or testing data. -Note - -Unreleased implementations (including proofs-of-concept demonstrating +**Note:** Unreleased implementations (including proofs-of-concept demonstrating that a particular MSC works) do not have to follow this process. 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. - When using unstable endpoints, they MUST include a vendor 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 backwards-incompatible way, the feature flag should also change 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. -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 implementation of the MSC, though the implementation does not need to be shipped anywhere and can therefore avoid the 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. -6. A spec PR is written to incorporate the changes into Matrix. -7. A spec release happens. -8. Implementations switch to using stable prefixes (e.g.: `/r0`) if the - server supports the specification version released. If the server - doesn't advertise the specification version, but does have the - feature flag, unstable prefixes should still be used. -9. A transition period of about 2 months starts immediately after the +1. Implementations can now switch to using stable prefixes + (for example, for an endpoint, moving from + `/unstable/org.matrix.mscxxxx/frobnicate` + to `/v1/frobnicate`), assuming that the change + is backwards compatible with older implementations. In the rare occasion + where backwards compatibility is not possible without a new spec release, + 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 implementations to switch to stable endpoints. For example, a server implementation should start asking client implementations to support @@ -466,9 +467,9 @@ com.example/new/endpoint`. In summary: -- Implementations MUST NOT use stable endpoints before the MSC is in - the spec. This includes NOT using stable endpoints in the period - between completion of FCP and release of the spec. passed. +- Implementations MUST NOT use stable endpoints before the MSC has + completed FCP. Once that has occurred, implementations are allowed + to use stable endpoints, but are not required to. - Implementations are able to ship features that are exposed to users by default before an MSC has been merged to the spec, provided they follow the process above.