370 lines
18 KiB
Markdown
370 lines
18 KiB
Markdown
# Matrix Specification Proposals
|
|
|
|
This repository contains proposals for changes to the [Matrix
|
|
Protocol](http://spec.matrix.org), aka "Matrix Spec Changes" (MSCs). The
|
|
[`proposals`](./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](https://spec.matrix.org) 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](https://matrix.org/foundation) 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](https://matrix.to/#/#matrix-spec:matrix.org) or [Office of the
|
|
Spec Core Team](https://matrix.to/#/#sct-office:matrix.org) Matrix rooms for
|
|
clarification.
|
|
|
|
### Summary of the process
|
|
|
|
The MSC process consists of three basic steps:
|
|
|
|
1. **Write up the proposal** in a
|
|
[markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#GitHub-flavored-markdown)
|
|
document. (There's a [proposal
|
|
template](proposals/0000-proposal-template.md), but don't feel bound by it.)
|
|
2. **Submit it as a Pull Request** to this repo, marking it as a draft until
|
|
it's ready for wider review.
|
|
3. **Seek review** from the community. Once people are generally happy with it,
|
|
ask the [Spec Core Team](https://matrix.org/foundation) to look at it in
|
|
[the Office of the SCT Matrix
|
|
room](https://matrix.to/#/#sct-office:matrix.org). 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](proposals/0000-proposal-template.md) 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](https://github.com/matrix-org/matrix-spec-proposals/pull/3030)."
|
|
* "A new field will be added to the response body of
|
|
[`/_matrix/client/v3/sync`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3sync)".
|
|
* Note: it is best to link to the latest stable version of the spec
|
|
(e.g. /v1.3, not /latest) - failing that,
|
|
[/unstable](https://spec.matrix.org/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](https://mermaid-js.github.io/mermaid/#/). See [this
|
|
guide](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)
|
|
for more information.
|
|
* Take a look at the [MSC Checklist](MSC_CHECKLIST.md). 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
|
|
|
|
1. Open a [Pull
|
|
Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
|
|
to add your proposal document to the [`proposals`](proposals) directory.
|
|
Note that this will require a GitHub account.
|
|
* [Mark your Pull Request as a
|
|
draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
|
|
for now.
|
|
2. 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!
|
|
3. Edit the pull request title to fit the format "MSC1234: Your proposal
|
|
title".
|
|
4. Once your proposal is correctly formatted and ready for review from the
|
|
wider ecosystem, [take your Pull Request out of draft
|
|
status](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review).
|
|
|
|
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](https://matrix.to/#/#matrix-spec:matrix.org).
|
|
|
|
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 the proposal is a work in progress, it's fine for it to be high level
|
|
and hand-wavy in places, but remember that before it can be accepted it needs
|
|
to be expanded to fully flesh out all the technical detail and edge cases.
|
|
|
|
At this stage the proposal should also be implemented as a proof of concept
|
|
somewhere to show that it _actually_ works in practice. This can be done on any
|
|
client or server and doesn't need to be merged or released.
|
|
|
|
#### 4. Entering Final Comment Period
|
|
|
|
After the MSC has been implemented, fully fleshed out, and generally feels
|
|
ready for final review, you should ask a member of the Spec Core Team to review it in
|
|
the public [Spec Core Team Office room on
|
|
Matrix](https://matrix.to/#/#sct-office:matrix.org). Someone from the SCT will
|
|
then review it, and if all looks well will propose FCP
|
|
to start.
|
|
|
|
At this point, other members of the SCT will look at the proposal and consider
|
|
it for inclusion in the spec.
|
|
|
|
After enough SCT members have approved the proposal, the MSC will enter
|
|
something called _Final Comment Period_. This is a 5 calendar day countdown to
|
|
give anyone one last chance to raise any blockers or concerns about the
|
|
proposed change. Typically MSCs pass this stage without incident, but it
|
|
nevertheless serves as a safeguard.
|
|
|
|
#### 5. The MSC is accepted
|
|
|
|
Once FCP has ended and the MSC pull request is merged, the proposed change is
|
|
considered officially part of the spec. Congratulations!
|
|
|
|
Clients and servers can now start using the change, even though at this stage
|
|
it still needs to be transcribed into the spec document. This happens over in
|
|
https://github.com/matrix-org/matrix-spec/ and you are very welcome to do it
|
|
yourself! Otherwise it will be handled by a Spec Core Team member. If you would
|
|
like help with writing spec PRs, feel free to join and ask questions in the
|
|
[Matrix Spec and Docs Authoring Room on Matrix](https://matrix.to/#/#matrix-docs:matrix.org).
|
|
|
|
### Other useful information
|
|
|
|
#### Unstable prefixes
|
|
|
|
"Unstable prefixes" are the namespaces which are used by implementations while
|
|
an MSC is not yet accepted.
|
|
|
|
For instance, an MSC might propose that a `m.space`
|
|
event type or an `/_matrix/client/v1/account/whoami` endpoint should exist.
|
|
However, implementations cannot use these *stable* identifiers until the MSC
|
|
has been accepted, as the underlying design may change at any time; the design is
|
|
*unstable*.
|
|
|
|
Instead, an MSC can define a namespace such as `org.matrix.msc1234` (using the real
|
|
MSC number once known) which is added to the stable identifier, allowing for
|
|
breaking changes between edits of the MSC itself, and preventing clashes with other
|
|
MSCs that might attempt to add the same stable identifiers.
|
|
|
|
For the above examples, this would mean using `org.matrix.msc1234.space` and
|
|
`/_matrix/client/unstable/org.matrix.msc1234/account/whoami`. It is also fine to
|
|
use more traditional forms of namespace prefixes, such as `com.example.*` (e.g.
|
|
`com.example.space`).
|
|
|
|
Note: not all MSCs need to make use of unstable prefixes. They are only needed if
|
|
implementations of your MSC need to exist in the wild before your MSC is accepted,
|
|
*and* the MSC defines new endpoints, field names, etc.
|
|
|
|
#### Unstable feature flags
|
|
|
|
It is common when implementing support for an MSC that a client may wish to check
|
|
if the homeserver it is communicating with supports an MSC.
|
|
Typically, this is handled by the MSC defining an
|
|
entry in the `unstable_features` dictionary of the
|
|
[`/_matrix/client/versions`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientversions)
|
|
endpoint, in the form of a new entry:
|
|
|
|
```json5
|
|
{
|
|
"unstable_features": {
|
|
"org.matrix.msc1234": true
|
|
}
|
|
}
|
|
```
|
|
|
|
... with a value of `true` indicating that the feature is supported, and `false`
|
|
or lack of the field altogether indicating the feature is not supported.
|
|
|
|
#### When can I use stable identifiers?
|
|
|
|
[According to the spec
|
|
process](https://spec.matrix.org/proposals/#early-release-of-an-mscidea): once
|
|
an MSC has been accepted, implementations are allowed to switch to *stable*
|
|
identifiers. However, the MSC is still not yet part of a released spec version.
|
|
|
|
In most cases, this is not an issue. For instance, if your MSC specifies a new
|
|
event type, you can now start sending events with those types!
|
|
|
|
Some MSCs introduce functionality where coordination between implementations is
|
|
needed. For instance, a client may want to know whether a homeserver supports
|
|
the stable version of a new endpoint before actually attempting to request it.
|
|
Or perhaps the new event type you're trying to send relies on the homeserver
|
|
recognising that new event type, and doing some work when it sees it.
|
|
|
|
At this point, it may be best to wait until a new spec version is released with
|
|
your changes. Homeservers that support the changes will eventually advertise
|
|
that spec version under `/versions`, and your client can check for that.
|
|
|
|
But if you really can't wait, then there is another option: the homeserver can
|
|
tell clients that it supports *stable* indentifiers for your MSC before it
|
|
enters a spec version, using yet another `unstable_features` flag:
|
|
|
|
```json5
|
|
{
|
|
"unstable_features": {
|
|
"org.matrix.msc1234": true,
|
|
"org.matrix.msc1234.stable": true
|
|
}
|
|
}
|
|
```
|
|
|
|
If a client sees that `org.matrix.msc1234.stable` is `true`, it knows that it
|
|
can start using stable identifiers for the new MSC, and the homeserver will
|
|
accept and act on them accordingly.
|
|
|
|
Note: While the general pattern of using the text ".stable" has emerged from
|
|
previous MSCs, you can pick any name you like. You need only to clearly state
|
|
their meaning, usually under an "Unstable prefixes" header in your MSC.
|
|
|
|
See
|
|
[MSC3827](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3827-space-explore.md#unstable-prefix)
|
|
for a good example of an MSC that wanted to use such a flag to speed up
|
|
implementation rollout, and how it did so.
|
|
|
|
#### Room versions
|
|
|
|
To summarize [the spec](https://spec.matrix.org/latest/rooms/) on room
|
|
versions: they are how servers agree upon algorithms in a decentralized world
|
|
like ours. Examples of changes that require a new room version include anything that changes:
|
|
* The format of the core event structure (such as renaming a top-level field,
|
|
or modifying [the redaction
|
|
algorithm](https://spec.matrix.org/latest/client-server-api/#redactions)),
|
|
therefore altering the [reference
|
|
hash](https://spec.matrix.org/latest/server-server-api/#calculating-the-reference-hash-for-an-event)
|
|
of an event.
|
|
* [The authorisation of
|
|
events](https://spec.matrix.org/latest/server-server-api/#authorization-rules)
|
|
(such as changes to power levels).
|
|
|
|
Unstable prefixes (see above) for room versions work the same as they do for
|
|
other identifiers; your unstable room version may be called
|
|
"org.matrix.msc1234".
|
|
|
|
In order for the changes to end up in a "real" room version (the ones listed in
|
|
the spec), it will need a second MSC which aggregates a bunch of functionality
|
|
from various MSCs into a single room version. Typically these sorts of curating
|
|
MSCs are written by the Spec Core Team given the complexity in wording, but
|
|
you're more than welcome to bring an MSC forward which makes the version real.
|
|
|
|
For an example of what introducing a new room version-required feature can look
|
|
like, see [MSC3667](https://github.com/matrix-org/matrix-doc/pull/3667). For an
|
|
example of what making a new "real" room version looks like, see
|
|
[MSC3604](https://github.com/matrix-org/matrix-doc/pull/3604).
|
|
|
|
#### Ownership of MSCs and closing them
|
|
|
|
If an author decides that they would no longer like to pursue their MSC, they
|
|
can either pass ownership of it off to someone else, or close it themselves.
|
|
|
|
* The author of an MSC can close their MSC at any time before FCP by simply
|
|
closing the pull request.
|
|
* To appoint another user as an author of the MSC (either to replace the author
|
|
entirely or to provide additional help), make a note in the MSC's PR
|
|
description by writing the following on its own line:
|
|
|
|
```
|
|
Author: @username
|
|
```
|
|
|
|
where `@username` is a valid GitHub username. Multiple such lines can be
|
|
added.
|
|
|
|
Finally, [give that user access to write to your fork of
|
|
matrix-spec-proposals on
|
|
GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository),
|
|
which your PR originates from. This will allow them to change the text of
|
|
your MSC.
|
|
|
|
Similar to accepting an MSC, the Spec Core Team may propose a Final Comment
|
|
Period with a disposition of "close". This can happen if the MSC appears
|
|
abandoned by its author, or the idea is widely rejected by the community. A
|
|
vote and final comment period will still be required for the motion to pass.
|
|
|
|
Additionally, FCP can be also proposed with a disposition of "postpone". This
|
|
may be done for MSCs for which the proposed changes do not make sense for the
|
|
current state of the ecosystem, but may make sense further down the road.
|
|
|
|
## Asking for help
|
|
|
|
The Matrix community and members of the Spec Core Team are here to help guide
|
|
you through the process!
|
|
|
|
If you'd just like to get initial feedback about an idea that's not fully
|
|
fleshed out yet, creating an issue at
|
|
https://github.com/matrix-org/matrix-spec/issues is a great place to start. Be
|
|
sure to search for any existing issues first to see if someone has already had
|
|
the same idea!
|
|
|
|
A few official rooms exist on Matrix where your questions can be answered, or
|
|
feedback on your proposal can be requested:
|
|
|
|
* [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) -
|
|
General chat for MSCs, the spec, and pretty much anything in that sphere.
|
|
* [#sct-office:matrix.org](https://matrix.to/#/#sct-office:matrix.org) - Where
|
|
the Spec Core Team hangs out and is available. This room is intended to have
|
|
extremely high signal and low noise, primarily to ensure that MSCs are not
|
|
falling through the cracks. If an MSC requires attention or comment from Spec
|
|
Core Team members, bring it up here.
|
|
* [#matrix-spec-process:matrix.org](https://matrix.to/#/#matrix-spec-process:matrix.org) - A
|
|
room dedicated to [the spec process
|
|
itself](https://spec.matrix.org/proposals/#process). If you have any
|
|
questions about or suggestions to improve the Matrix Spec process, ask them
|
|
here.
|
|
* [#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) - A
|
|
quieter room for discussion of the [formal spec
|
|
text](https://spec.matrix.org) and [matrix.org](https://matrix.org) website. |