wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #2433 from matrix-org/travis/spec/msc2324-early-releases

Browse source 
Attempt to convert MSC2324 (facilitating early releases of implementations) to reality
This commit is contained in:
Travis Ralston 2020-05-21 07:41:45 -06:00 • committed by GitHub
commit 899db411a3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 96 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

97
specification/proposals_intro.rst
View file

@ -230,7 +230,8 @@ follows:
comments and in relevant rooms on Matrix. Discussion outside of GitHub should
be summarised in a comment on the PR.
- When a member of the Spec Core Team believes that no new discussion points are
being made, they will propose a motion for a final comment period (FCP),
being made, and the proposal has suitable evidence of working (see `implementing a
proposal`_ below), they will propose a motion for a final comment period (FCP),
along with a *disposition* of either merge, close or postpone. This FCP is
provided to allow a short period of time for any invested party to provide a
final objection before a major decision is made. If sufficient reasoning is
@ -371,6 +372,100 @@ though that can always change as priorities evolve. We still encourage that MSCs
opened, even if not the focus for the time being, as they can still make progress and
even be merged without the Spec Core Team focusing on them specifically.
Implementing a proposal
-----------------------
As part of the proposal process the spec core team will require evidence of the MSC
working in order for it to move into FCP. This can usually be a branch/pull request
to whichever implementation of choice that proves the MSC works in practice, though
in some cases the MSC itself will be small enough to be considered proven. Where it's
unclear if a MSC will require an implementation proof, ask in `#matrix-spec:matrix.org
<https://matrix.to/#/#matrix-spec:matrix.org>`_.
Early release of a MSC/idea
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To help facilitate early releases of software dependent on a spec 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 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 unstable
feature flags as appropriate.
* When using unstable endpoints, they MUST include a vendor prefix. For example:
``/_matrix/client/unstable/com.example/login``. Vendor prefixes throughout Matrix
always use the Java package naming convention. The MSC for the feature should
identify which preferred vendor prefix is to be used by early adopters.
* Note that unstable namespaces do not automatically inherit endpoints from stable
namespaces: for example, the fact that ``/_matrix/client/r0/sync`` exists does
not imply that ``/_matrix/client/unstable/com.example/sync`` exists.
* If the client needs to be sure the server supports the feature, an unstable
feature flag that MUST be vendor prefixed is to be used. This kind of flag shows
up in the ``unstable_features`` section of ``/versions`` as, for example,
``com.example.new_login``. The MSC for the feature should identify which preferred
feature flag is to be used by early adopters.
* When using this approach correctly, the implementation can ship/release the
feature at any time, so long as the implementation is able to accept the technical
debt that results from needing to provide adequate backwards and forwards
compatibility. The implementation MUST support the flag (and server-side implementation) disappearing and be
generally safe for users. Note that implementations early in the MSC review
process may also be required to provide backwards compatibility with earlier
editions of the proposal.
* If the implementation cannot support the technical debt (or if it's impossible
to provide forwards/backwards compatibility - e.g. a user authentication change
which can't be safely rolled back), the implementation should not attempt to
implement the feature and should instead wait for a spec release.
* 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 review per above.
4. 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 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 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 the stable endpoints 2 months after the spec
release, if they haven't already. The same applies in the reverse: if clients
cannot switch to stable prefixes because server implementations haven't started
supporting the new spec release, some noise should be raised in the general direction
of the implementation.
.. Note::
MSCs MUST still describe what the stable endpoints/feature looks like with a note
towards the bottom for what the unstable feature flag/prefixes are. For example,
a MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
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 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.
* Implementations SHOULD be wary of the technical debt they are incurring by moving faster
than the spec.
* The vendor prefix is chosen by the developer of the feature, using the Java package
naming convention. The foundation's preferred vendor prefix is `org.matrix`.
* The vendor prefixes, unstable feature flags, and unstable endpoints should be included
in the MSC, though the MSC MUST be written in a way that proposes new stable endpoints.
Typically this is solved by a small table at the bottom mapping the various values
from stable to unstable.
Proposal Tracking
-----------------