1   Proposals for Spec Changes to Matrix

If you are interested in submitting a change to the Matrix Specification, please take note of the following guidelines.

Most changes to the Specification require a formal proposal. Bug fixes, typos, and clarifications to existing behaviour do not need proposals - see the contributing guide for more information on what does and does not need a proposal.

The proposal process involves some technical writing, having it reviewed by everyone, having the proposal being accepted, then actually having your ideas implemented as committed changes to the Specification repository.

Meet the members of the Core Team, a group of individuals tasked with ensuring the spec process is as smooth and painless as possible. Members of the Spec Core Team will do their best to participate in discussion, summarise when things become long-winded, and generally try to act towards the benefit of everyone. As a majority, team members have the ability to change the state of a proposal, and individually have the final say in proposal discussion.

2   Guiding Principles

Proposals must act to the greater benefit of the entire Matrix ecosystem, rather than benefiting or privileging any single player or subset of players - and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as a neutral custodian for Matrix on behalf of the whole ecosystem.

For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That includes client users, server admins, client developers, bot developers, bridge and application service developers, users and admins who are indirectly using Matrix via 3rd party networks which happen to be bridged, server developers, room moderators and admins, companies/projects building products or services on Matrix, spec contributors, translators, and those who created it in the first place.

"Greater benefit" could include maximising:

  • the number of end-users reachable on the open Matrix network
  • the number of regular users on the Matrix network (e.g. 30-day retained federated users)
  • the number of online servers in the open federation
  • the number of developers building on Matrix
  • the number of independent implementations which use Matrix
  • the number of bridged end-users reachable on the open Matrix network
  • the signal-to-noise ratio of the content on the open Matrix network (i.e. minimising spam)
  • the ability for users to discover content on their terms (empowering them to select what to see and what not to see)
  • the quality and utility of the Matrix spec (as defined by ease and ability with which a developer can implement spec-compliant clients, servers, bots, bridges, and other integrations without needing to refer to any other external material)

In addition, proposal authors are expected to uphold the following values in their proposed changes to the Matrix protocol:

  • Supporting the whole long-term ecosystem rather than individual stakeholder gain
  • Openness rather than proprietary lock-in
  • Interoperability rather than fragmentation
  • Cross-platform rather than platform-specific
  • Collaboration rather than competition
  • Accessibility rather than elitism
  • Transparency rather than stealth
  • Empathy rather than contrariness
  • Pragmatism rather than perfection
  • Proof rather than conjecture

Please see MSC1779 for full details of the project's Guiding Principles.

3   Technical notes

Proposals must develop Matrix as a layered protocol: with new features building on layers of shared abstractions rather than introducing tight vertical coupling within the stack. This ensures that new features can evolve rapidly by building on existing layers and swapping out old features without impacting the rest of the stack or requiring substantial upgrades to the whole ecosystem. This is critical for Matrix to rapidly evolve and compete effectively with centralised systems, despite being a federated protocol.

For instance, new features should be implemented using the highest layer abstractions possible (e.g. new event types, which layer on top of the existing room semantics, and so don't even require any API changes). Failing that, the next recourse would be backwards-compatible changes to the next layer down (e.g. room APIs); failing that, considering changes to the format of events or the DAG; etc. It would be a very unusual feature which doesn't build on the existing infrastructure provided by the spec and instead created new primitives or low level APIs.

Backwards compatibility is very important for Matrix, but not at the expense of hindering the protocol's evolution. Backwards incompatible changes to endpoints are allowed when no other alternative exists, and must be versioned under a new major release of the API. Backwards incompatible changes to the room algorithm are also allowed when no other alternative exists, and must be versioned under a new version of the room algorithm.

There is sometimes a dilemma over where to include higher level features: for instance, should video conferencing be formalised in the spec, or should it be implemented via widgets? Should reputation systems be specified? Should search engine behaviour be specified?

There is no universal answer to this, but the following guidelines should be applied:

  1. If the feature would benefit the whole Matrix ecosystem and is aligned with the guiding principles above, then it should be supported by the spec.
  2. If the spec already makes the feature possible without changing any of the implementations and spec, then it may not need to be added to the spec.
  3. However, if the best user experience for a feature does require custom implementation behaviour then the behaviour should be defined in the spec such that all implementations may implement it.
  4. However, the spec must never add dependencies on unspecified/nonstandardised 3rd party behaviour.

As a worked example:

  1. Video conferencing is clearly a feature which would benefit the whole ecosystem, and so the spec should find a way to make it happen.
  2. Video conferencing can be achieved by widgets without requiring any compulsory changes to changes to clients nor servers to work, and so could be omitted from the spec.
  3. A better experience could be achieved by embedding Jitsi natively into clients rather than using a widget...
  4. ...except that would add a dependency on unspecified/nonstandardised 3rd party behaviour, so must not be added to the spec.

Therefore, our two options in the specific case of video conferencing are either to spec SFU conferencing semantics for WebRTC (or refer to an existing spec for doing so), or to keep it as a widget-based approach (optionally with widget extensions specific for more deeply integrating video conferencing use cases).

As an alternative example: it's very unlikely that "how to visualise Magnetic Resonsance Imaging data over Matrix" would ever be added to the Matrix spec (other than perhaps a custom event type in a wider standardised Matrix event registry) given that the spec's existing primitives of file transfer and extensible events (MSC1767) give excellent tools for transfering and visualising arbitrary rich data.

Supporting public search engines are likely to not require custom spec features (other than possibly better bulk access APIs), given they can be implemented as clients using the existing CS API. An exception could be API features required by decentralised search infrastructure (avoiding centralisation of power by a centralised search engine).

Features such as reactions, threaded messages, editable messages, spam/abuse/content filtering (and reputation systems), are all features which would clearly benefit the whole Matrix ecosystem, and cannot be implemented in an interoperable way using the current spec; so they necessitate a spec change.

4   Process

The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as follows:

  • Create a first draft of your proposal using GitHub-flavored markdown
    • In the document, clearly state the problem being solved, and the possible solutions being proposed for solving it and their respective trade-offs.
    • Proposal documents are intended to be as lightweight and flexible as the author desires; there is no formal template; the intention is to iterate as quickly as possible to get to a good design.
    • However, a template with suggested headers is available to get you started if necessary.
    • Take care in creating your proposal. Specify your intended changes, and give reasoning to back them up. Changes without justification will likely be poorly received by the community.
  • Fork and make a PR to the matrix-doc repository. The ID of your PR will become the MSC ID for the lifetime of your proposal.
    • The proposal must live in the proposals/ directory with a filename that follows the format 1234-my-new-proposal.md where 1234 is the MSC ID.
    • Your PR description must include a link to the rendered markdown document and a summary of the proposal.
    • It is often very helpful to link any related MSCs or matrix-doc issues to give context for the proposal.
    • Additionally, please be sure to sign off your proposal PR as per the guidelines listed on CONTRIBUTING.rst.
  • Gather feedback as widely as possible.
    • The aim is to get maximum consensus towards an optimal solution. Sometimes trade-offs are required to meet this goal. Decisions should be made to the benefit of all major use cases.
    • A good place to ask for feedback on a specific proposal is #matrix-spec:matrix.org. If preferred, an alternative room can be created and advertised in #matrix-spec:matrix.org. Please also link to the room in your PR description.
    • For additional discussion areas, know that that #matrix-dev:matrix.org is for developers using existing Matrix APIs, #matrix:matrix.org is for users trying to run Matrix apps (clients & servers) and #matrix-architecture:matrix.org is for cross-cutting discussion of matrix's architectural design.
    • The point of the spec proposal process is to be collaborative rather than competitive, and to try to solve the problem in question with the optimal set of trade-offs. The author should neutrally gather the various viewpoints and get consensus, but this can sometimes be time-consuming (or the author may be biased), in which case an impartial 'shepherd' can be assigned to help guide the proposal through this process instead. A shepherd is typically a neutral party from the Spec Core Team or an experienced member of the community. There is no formal process for assignment. Simply ask for a shepherd to help get your proposal through and one will be assigned based on availability. Having a shepherd is not a requirement for proposal acceptance.
  • Members of the Spec Core Team and community will review and discuss the PR in the 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), 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 given, an FCP can be cancelled. It is often preceded by a comment summarising the current state of the discussion, along with reasoning for its occurrence.
  • A concern can be raised by a Spec Core Team member at any time, which will block an FCP from beginning. An FCP will only begin when 75% of the members of the Spec Core Team team agree on its outcome, and all existing concerns have been resolved.
  • The FCP will then begin and last for 5 days, giving anyone else some time to speak up before it concludes. On its conclusion, the disposition of the FCP will be carried out. If sufficient reasoning against the disposition is raised, the FCP can be cancelled and the MSC will continue to evolve accordingly.
  • Once the proposal has been accepted and merged, it is time to submit the actual change to the Specification that your proposal reasoned about. This is known as a spec PR. However in order for the spec PR to be accepted, an implementation must be shown to prove that it works well in practice. A link to the implementation should be included in the PR description. In addition, any significant unforeseen changes to the original idea found during this process 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.
    • Similar to the proposal PR, please sign off the spec PR as per the guidelines on CONTRIBUTING.rst.
  • Your PR will then be reviewed and hopefully merged on the grounds it is implemented sufficiently. If so, then give yourself a pat on the back knowing you've contributed to the Matrix protocol for the benefit of users and developers alike :)

The process for handling proposals is shown visually in the following diagram. Note that the lifetime of a proposal is tracked through the corresponding labels for each stage on the matrix-doc issue and pull request trackers.

                          +                          +
        Proposals         |          Spec PRs        |  Additional States
        +-------+         |          +------+        |  +---------------+
                          |                          |
+----------------------+  |         +---------+      |    +-----------+
|                      |  |         |         |      |    |           |
|      Proposal        |  |  +------= Spec PR |      |    | Postponed |
| Drafting and Initial |  |  |      | Missing |      |    |           |
|  Feedback Gathering  |  |  |      |         |      |    +-----------+
|                      |  |  |      +----+----+      |
+----------+-----------+  |  |           |           |    +----------+
           |              |  |           v           |    |          |
           v              |  |  +-----------------+  |    |  Closed  |
 +-------------------+    |  |  |                 |  |    |          |
 |                   |    |  |  | Spec PR Created |  |    +----------+
 |    Proposal PR    |    |  |  |  and In Review  |  |
 |     In Review     |    |  |  |                 |  |
 |                   |    |  |  +--------+--------+  |
 +---------+---------+    |  |           |           |
           |              |  |           v           |
           v              |  |     +-----------+     |
+----------------------+  |  |     |           |     |
|                      |  |  |     |  Spec PR  |     |
|    Proposed Final    |  |  |     |  Merged!  |     |
|    Comment Period    |  |  |     |           |     |
|                      |  |  |     +-----------+     |
+----------+-----------+  |  |                       |
           |              |  |                       |
           v              |  |                       |
+----------------------+  |  |                       |
|                      |  |  |                       |
| Final Comment Period |  |  |                       |
|                      |  |  |                       |
+----------+-----------+  |  |                       |
           |              |  |                       |
           v              |  |                       |
+----------------------+  |  |                       |
|                      |  |  |                       |
| Final Comment Period |  |  |                       |
|       Complete       |  |  |                       |
|                      |  |  |                       |
+----------+-----------+  |  |                       |
           |              |  |                       |
           +-----------------+                       |
                          |                          |
                          +                          +

5   Lifetime States

Note: All labels are to be placed on the proposal PR.

Name GitHub Label Description
Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with [WIP] to make it easier for reviewers to skim their notifications list.
Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Spec Core Team and community
Proposed Final Comment Period proposed-final-comment-period Currently awaiting signoff of a 75% majority of team members in order to enter the final comment period
Final Comment Period final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement
Final Commment Period Complete finished-final-comment-period The final comment period has been completed. Waiting for a demonstration implementation
Spec PR Missing spec-pr-missing The proposal has been agreed, and proven with a demonstration implementation. Waiting for a PR against the Spec
Spec PR In Review spec-pr-in-review The spec PR has been written, and is currently under review
Spec PR Merged merged A proposal with a sufficient working implementation and whose Spec PR has been merged!
Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future
Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance
Obsolete obsolete A proposal which has been made obsolete by another proposal or decision elsewhere.

6   Proposal Tracking

This is a living document generated from the list of proposals on the issue and pull request trackers of the matrix-doc repo.

We use labels and some metadata in MSC PR descriptions to generate this page. Labels are assigned by the Spec Core Team whilst triaging the proposals based on those which exist in the matrix-doc repo already.

It is worth mentioning that a previous version of the MSC process used a mixture of GitHub issues and PRs, leading to some MSC numbers deriving from GitHub issue IDs instead. A useful feature of GitHub is that it does automatically resolve to an issue, if an issue ID is placed in a pull URL. This means that https://github.com/matrix-org/matrix-doc/pull/$MSCID will correctly resolve to the desired MSC, whether it started as an issue or a PR.

Other metadata:

  • The MSC number is taken from the GitHub Pull Request ID. This is carried for the lifetime of the proposal. These IDs do not necessary represent a chronological order.
  • The GitHub PR title will act as the MSC's title.
  • Please link to the spec PR (if any) by adding a "PRs: #1234" line in the issue description.
  • The creation date is taken from the GitHub PR, but can be overridden by adding a "Date: yyyy-mm-dd" line in the PR description.
  • Updated Date is taken from GitHub.
  • Author is the creator of the MSC PR, but can be overridden by adding a "Author: @username" line in the body of the issue description. Please make sure @username is a GitHub user (include the @!)
  • A shepherd can be assigned by adding a "Shepherd: @username" line in the issue description. Again, make sure this is a real GitHub user.

7   Tables of Tracked Proposals

7.1   <work-in-progress>

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC2438 [WIP] MSC2438: Local and Federated User Erasure Requests 2020-02-19 2020-03-27   @anoadragon453 None  
MSC2474 MSC2474: Add key backup version to SSSS account data 2020-03-26 2020-03-27   @uhoreg None  

7.2   proposal-in-review

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC2380 MSC2380: Matrix Media Information API 2019-12-05 2020-01-14   @turt2live None  
MSC2385 MSC2385: Disable URL Previews, alternative method 2019-12-08 2020-02-26   @Sorunome None  
MSC2390 MSC2390: On the EDU-to-PDU transition. 2019-12-18 2020-01-16   @tulir None  
MSC2389 MSC2389: Toward the EDU-to-PDU transition: Typing. 2019-12-18 2020-01-14   @tulir None  
MSC2388 MSC2388: Toward the EDU-to-PDU transition: Read Receipts. 2019-12-18 2020-01-21   @tulir None  
MSC2391 MSC2391: Federation point-queries. 2019-12-19 2019-12-19   @tulir None  
MSC2399 MSC2399: Reporting that decryption keys are withheld 2020-01-02 2020-03-19   @uhoreg None  
MSC2398 MSC2398: proposal to allow mxc:// in the "a" tag within messages 2020-01-02 2020-01-03   @eras None  
MSC2403 MSC2403: Add "knock" feature 2020-01-09 2020-02-13   @Sorunome None  
MSC2409 MSC2409: Proposal to send EDUs to appservices 2020-01-14 2020-03-27   @Sorunome None  
MSC2413 MSC2413: Remove client_secret 2020-01-17 2020-03-05   @anoadragon453 None  
MSC2416 MSC2416: Enhance m.login.token authentication type 2020-01-18 2020-03-27   @Sorunome None  
MSC2414 MSC2414: Make reason optional for reporting content 2020-01-18 2020-03-27   @iinuwa None  
MSC2427 MSC2427: Proposal for JSON-based message formatting 2020-01-24 2020-03-10   @tulir None  
MSC2425 MSC2425: Remove Authentication on /submitToken Identity Service API 2020-01-24 2020-03-27   @anoadragon453 None  
MSC2437 MSC2437: Store tagged events in Room Account Data 2020-02-18 2020-03-05   @giomfo None  
MSC2444 MSC2444: peeking over federation via /peek 2020-02-24 2020-03-05   @ara4n None  
MSC2448 MSC2448: Using Blurhash in Media Events 2020-02-27 2020-03-27   @anoadragon453 None  
MSC2454 MSC2454: Support UI interactive auth for SSO 2020-03-09 2020-03-30   @clokep None  
MSC2461 MSC2461: Proposal for Authenticated Content Repository API 2020-03-15 2020-03-28   @SyrupThinker None  
MSC2463 MSC2463: Exclusion of MXIDs in push rules content matching 2020-03-18 2020-03-27   @pacien None  
MSC2472 MSC2472: Symmetric SSSS 2020-03-24 2020-03-30   @uhoreg None  
MSC2477 MSC2477: User-defined ephemeral events in rooms 2020-03-28 2020-03-30   @ananace None  

7.3   proposed-final-comment-period

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC2457 MSC2457: Invalidating devices during password modification 2020-03-12 2020-03-27   @clokep None  
MSC2472 MSC2472: Symmetric SSSS 2020-03-24 2020-03-30   @uhoreg None  
MSC2475 MSC2475: API versioning 2020-03-27 2020-03-30   @turt2live None  

7.6   spec-pr-missing

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC2422 MSC2422: Allow color on font tag 2020-01-23 2020-03-24   @deepbluev7 None  
MSC2432 MSC2432: Updated semantics for publishing room aliases 2020-02-10 2020-03-25   @richvdh None  

7.8   merged

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC2451 MSC2451: Remove query_auth federation endpoint. 2020-03-03 2020-03-24   @clokep None  

7.10   abandoned

No proposals.

7.11   obsolete

No proposals.