An excerpt from the repository, fetched Nov 12, 2026.
Read the project’s introduction
Matrix Specification Proposals
This repository contains proposals for changes to the Matrix
Protocol, aka "Matrix Spec Changes" (MSCs). The
proposals directory contains MSCs which have been accepted.
See below for instructions for creating new
proposals. See also https://spec.matrix.org/proposals/ for more
information on the MSC process, in particular
https://spec.matrix.org/proposals/#process.
The source of the Matrix specification itself is maintained at
https://github.com/matrix-org/matrix-spec.
The Matrix Spec Process
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. This is why
it's important for an MSC to be fully fleshed out in technical detail, as once
merged it's immediately part of the formal spec (even though it still needs to
be transcribed into the actual spec itself).
What changes need to follow this process?
In most cases a change to the Matrix protocol will
require an MSC. Changes that would not require an MSC are typically small and
uncontentious, or are simply clarifications to the spec. Fixing typos in the
spec do not require an MSC. In most cases, removing ambiguities do not either.
The exception may be if implementations in the ecosystem have differing views
on clarifying the ambiguity. In that case, an MSC is typically the best place
to reach consensus.
Ultimately, the Spec Core Team have the final
say on this, 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.
Summary of the process
The MSC process consists of three basic steps:
Write up the proposal in a
markdown
document. (There's a proposal
template, but don't feel bound by it.)
Submit it as a Pull Request to this repo, marking it as a draft until
it's ready for wider review.
Seek review from the community. Once people are generally happy with it,
ask the Spec Core Team to look at it in
the Office of the SCT Matrix
room. When the SCT are happy
with the proposal, and after a successful voting process, your pull request
is merged and the MSC is now officially accepted as part of the Matrix
Spec and can be used 🎉
For simple changes 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.
Below is various guidance to try and help make the experience smoother.
Guidance on the process
1. Writing the proposal
Come up with an idea. The idea can be for anything, but the solution (MSC)
needs to benefit the Matrix ecosystem rather than yourself (or your company)
specifically. Sometimes this means that the solution needs to be more generic
than the specific itch that you are trying to scratch.
Remember that an MSC is a formal technical document which will be used by
others in the wider community to judge if the proposal should be accepted and
to actually implement the changes in clients and servers. This means that 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.
There's a proposal template under
docs/0000-proposal.md, but you don't necessarily need to use it. Covering the
same major points is fine.
Note: At this stage, you won't have an MSC number, so feel free to use
0000, XXXX, or whatever other placeholder you feel comfortable with.
Some tips for MSC writing:
Please wrap your lines to 120 characters maximum.
This allows readers to review your markdown without needing to horizontally
scroll back and forth. Many markdown text editors have this feature.
If you are referencing an existing endpoint in the spec, or another MSC, it
is very helpful to add a link to them so the reader does not need to search
themselves. Examples:
"This MSC proposals an alternative to
MSC3030."
"A new field will be added to the response body of
/_matrix/client/v3/sync".
Note: it is best to link to the latest stable version of the spec
(e.g. /v1.3, not /latest) - failing that,
/unstable if the change is not
yet in a released spec version.
GitHub supports rendering fancy diagrams from text with very little
effort using Mermaid. See this
guide
for more information.
Take a look at the MSC Checklist. When it comes time for
the Spec Core Team to review your MSC for acceptance, they'll use the items
on this checklist as a guide.
2. Submitting a Pull Request
Open a Pull
Request
to add your proposal document to the proposals directory.
Note that this will require a GitHub account.
Mark your Pull Request as a
draft
for now.
The MSC number is the number of the pull request that is automatically
assigned by GitHub. Go back through and edit the document accordingly. Don't
forget the file name itself!
Edit the pull request title to fit the format "MSC1234: Your proposal
title".
Once your proposal is correctly formatted and ready for review from the
wider ecosystem, take your Pull Request out of draft
status.
The Spec Core Team will notice this and apply various labels/status tracking to
your MSC, which will announce it to the wider world.
3. Seeking review
Seek review from the Matrix community. Generally this will happen naturally,
but if you feel that your proposal is lacking review then ask for people's
opinion in the Matrix Spec room on
Matrix.
Reviews can take many forms, and do not need to be done solely by members of
the Spec Core Team. Getting other people who are familiar with the area of
Matrix you are proposing changes to is a great first step; especially those who
may be implementing these changes in clients and/or homeservers.
While
Read the full README on GitHub
