matrix-spec-proposals is where the Matrix protocol actually changes

Accepted MSCs live in the proposals directory, the spec lives elsewhere

This repository contains proposals for changes to the Matrix protocol, aka Matrix Spec Changes, or MSCs. The proposals directory contains MSCs which have been accepted.

The distinction between the two repositories is the first thing to understand. The source of the Matrix specification itself is maintained at matrix-org/matrix-spec. This repository is the change process, and the accepted proposals.

The reason for the split is stated in the process description, and it is a good reason. An MSC is meant to be a technical document that unambiguously describes a change to the Matrix spec, while also justifying why the change should be made. The document is used both to judge whether the change should be made as described and by developers to actually implement the changes. That is why it is important for an MSC to be fully fleshed out in technical detail, as once merged it is immediately part of the formal spec, even though it still needs to be transcribed into the actual spec itself.

That last clause is the subtlety. An accepted MSC is normative immediately, in the sense that the community treats it as decided, but the specification document still has to be updated by hand to describe the behaviour in the spec's own words. So for a period, the two can disagree on wording, and the MSC is the newer statement of intent.

The practical consequence for a reader is that the accepted proposals directory is a record of the decisions that were accepted, including the ones that were contentious.

Three steps: write, submit as a draft pull request, then seek review

The process description is explicit about the sequence, and the summary of it is short enough to memorise.

The first step is to write up the proposal in a markdown document. There is a proposal template, but the documentation says not to feel bound by it. The second step is to submit it as a pull request to this repository, marking it as a draft until it is ready for wider review. The third step is to seek review from the community. Once people are generally happy with it, you ask the Spec Core Team to look at it in the Office of the SCT Matrix room, and when the SCT are happy with the proposal and after a successful voting process, the pull request is merged and the MSC is now officially accepted as part of the Matrix spec.

The mechanics of the pull request are worth knowing because the MSC number is not chosen by the author. The MSC number is the number of the pull request that is automatically assigned by GitHub, so you go back through and edit the document accordingly, and do not forget the file name itself. The pull request title must fit the format of the MSC number followed by the proposal title.

The draft status is part of the process rather than an accident. The instruction is to mark the pull request as a draft for now, and then take it out of draft status once the proposal is correctly formatted and ready for review from the wider ecosystem. The Spec Core Team notices the transition and applies labels and status tracking.

For simple changes the documentation says this is really all you need to know. For larger or more controversial changes, getting an MSC merged can take more time and effort, but the overall process remains the same.

Which changes need an MSC, and which are just clarifications

The question of when the process applies is answered more carefully than you might expect, and the answer reflects a real governance position.

In most cases a change to the Matrix protocol will require an MSC. Changes that would not require one are typically small and uncontentious, or are simply clarifications to the spec. Fixing typos does not require an MSC, and in most cases removing ambiguities does not either.

The exception is spelled out: it may be the case if implementations in the ecosystem have differing views on clarifying the ambiguity, and in that case an MSC is typically the best place to reach consensus.

That clause is the interesting one, because it shows the process is not really about document size but about disagreement. A clarification is uncontroversial only as long as everyone agrees what it means. If two client implementations read the same sentence differently, the ambiguity is not a wording problem, it is a pending interoperability bug, and the MSC is where it gets settled. That is a sensible rule, and it also explains why the process is not applied to typo fixes: a typo fix cannot hide a semantic dispute.

The escalation path is also given. Ultimately the Spec Core Team have the final say, but generally if the change would require updates to a non-insignificant portion of the Matrix implementation ecosystem or would be met with contention, an MSC is the best route to take. You can also ask in the Matrix Spec or Office of the Spec Core Team Matrix rooms for clarification.

The one requirement the documentation places on the content itself is a scope requirement rather than a technical one. The idea can be for anything, but the solution needs to benefit the Matrix ecosystem rather than yourself, or your company, specifically. Sometimes that means the solution needs to be more generic than the specific itch you are trying to scratch.

The MSC checklist is what the reviewers actually work from

There is a checklist file, MSC_CHECKLIST.md, and the documentation explains its role plainly: when it comes time for the Spec Core Team to review your MSC for acceptance, they will use the items on this checklist as a guide.

That is the most useful single document in the repository for a prospective author, because it converts the process from a set of principles into a list of things to have ready. A proposal that satisfies the checklist is close to acceptance; one that does not will go back.

The writing guidance around it is equally practical, and it is mostly about making the document reviewable rather than about the protocol.

Wrap your lines to 120 characters maximum, so readers can review the markdown without needing to scroll horizontally. Many markdown editors have this feature.

Link to existing endpoints and other MSCs, so the reader does not need to search for them. The documentation gives the pattern, such as proposing an alternative to an existing MSC by linking to its pull request, and describing a new field added to the response body of a client-server API endpoint. There is a specific note about linking to the latest stable version of the spec rather than the latest version, and failing that, to the unstable version if the change is not yet in a released spec version.

Use Mermaid diagrams, since GitHub renders them from text with very little effort.

And the naming of the proposal itself is left open at this stage. You will not have an MSC number yet, so you are free to use 0000, XXXX, or whatever other placeholder you are comfortable with. The template is described as living under docs/0000-proposal.md in one place and as proposals/0000-proposal-template.md in another, and either way the documentation says you do not necessarily need to use it, and that covering the same major points is fine.

An accepted proposal must specify the edge cases, not just the happy path

One requirement runs through the whole document, and it is the requirement that most distinguishes an MSC from a feature request.

For an MSC to be accepted it should include justifications and describe the technical changes unambiguously, including specifying what happens in any and all edge cases.

That clause is demanding, and it is deliberate. An MSC is used by two different audiences at once, the people judging whether the change should be made and the people implementing it. A document that describes the happy path but is vague about what happens when a client sends a malformed field, or when two servers disagree, or when the feature is used in a room type that did not exist when the proposal was written, is useful to the first audience and useless to the second.

The Matrix protocol has a large surface of optional features and negotiated capabilities, and that shape is what makes the edge-case requirement bite. A new field in a sync response has to be specified for a client that does not understand it, for a server that receives one from a newer client, and for the intermediate case where a client library parses the JSON but an application does not know the field.

This is also why the process is slower than a normal pull request, and the documentation acknowledges that without pretending otherwise. For larger or more controversial changes, getting an MSC merged can take more time and effort. The trade is that the outcome is a document that an independent implementer in a different language, in a different project, can implement from without asking the author a question.

A quiet repository, and where to look for the current process rules

The repository itself is small. The top level holds the README, CONTRIBUTING.md, the MSC_CHECKLIST.md, the LICENSE, and the proposals/ directory, plus an.editorconfig and the.github directory. There is no code, and the primary language is listed as Python, which reflects the tooling around the document rather than anything that runs.

The licence is Apache-2.0, with the LICENSE file in the repository as the authoritative text, and this is a licensing statement rather than legal advice.

The release record is thin, which is what you would expect from a repository whose output is accepted documents rather than software. The recent releases are v1.2 on 2022-02-02, v1.1 on 2021-11-09 and a server_server/r0.1.4 on 2020-05-27, and the repository is not archived with the last push on 2026-10-19.

The documentation points to the live process documentation at spec.matrix.org/proposals/, and in particular the process section there, which is where the current rules live rather than in the README. That distinction matters, because the README in this repository is a convenience copy and the published process documentation is the authoritative one.

The collaboration channels are Matrix rooms, which is fitting for a protocol whose whole point is federated communication. You can ask in the Matrix Spec room or the Office of the Spec Core Team room for clarification, and the README points to the Spec Core Team page on the Matrix Foundation site for who they are.

The MSC number being the pull request number is a small but significant design decision. It means the identity of a proposal is tied to the discussion that produced it, so the pull request is not just a delivery mechanism but the permanent record of the review, and anyone can read why a proposal was written the way it was.

Editorial conclusion

Adopt matrix-spec-proposals if you implement Matrix or need to know why a protocol behaviour exists, because the accepted MSCs are the authoritative explanation and the repository is where the reasoning is written down. Do not treat it as the specification itself, since the source of the Matrix specification is maintained separately in matrix-org/matrix-spec. Before you file a proposal, read MSC_CHECKLIST.md, because the Spec Core Team reviews against those items, and check whether your change is small and uncontentious enough to skip the process entirely.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. matrix-org/matrix-spec-proposals on GitHub
4. README
5. Releases