Skip to content

Commit 1676be3

Browse files
anoadragon453richvdh
anoadragon453
and
richvdh
authored
Update the README with details on the Matrix spec process + unstable prefixes (#3891)
Co-authored-by: Richard van der Hoff <[email protected]>
1 parent 85e0444 commit 1676be3

File tree

2 files changed

+287
-23
lines changed

2 files changed

+287
-23
lines changed

‎CONTRIBUTING.md

+4-15
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,10 @@ Contributing to `matrix-spec-proposals`
33

44
Thank you for taking the time to contribute to Matrix!
55

6-
This repository is for proposals to changes to the Matrix protocol. The process
7-
for submitting a proposal is spelt out in detail at
8-
https://spec.matrix.org/proposals (in particular,
9-
https://spec.matrix.org/proposals/#process).
10-
11-
However, in brief, it amounts to:
12-
13-
1. Create a [pull request][1] adding a new file to the
14-
[`proposals`](./proposals) directory, expaining what you think should be
15-
changed, and why. (Ideally, the file should be numbered according to the
16-
pull request number, which normally means you need to rename it once you've
17-
opened the PR.)
18-
19-
2. Seek feedback on your proposal, for example in
20-
[#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org).
6+
This repository is for proposals for changes to the Matrix protocol. The process
7+
for submitting a proposal is described in
8+
[this repository's README](README.md#the-matrix-spec-process) or in further detail at
9+
https://spec.matrix.org/proposals/#process.
2110

2211
Sign off
2312
--------

‎README.md

+283-8
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,290 @@
11
# Matrix Specification Proposals
22

33
This repository contains proposals for changes to the [Matrix
4-
Protocol](http://spec.matrix.org), aka "Matrix Spec Changes" (MSCs).
4+
Protocol](http://spec.matrix.org), aka "Matrix Spec Changes" (MSCs). The
5+
[`proposals`](./proposals) directory contains MSCs which have been accepted.
56

6-
The [`proposals`](./proposals) directory contains MSCs which have been
7-
accepted.
8-
9-
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for some notes on making new
10-
proposals. See also https://spec.matrix.org/unstable/proposals/ for more
7+
See below for instructions for creating new
8+
proposals. See also https://spec.matrix.org/proposals/ for more
119
information on the MSC process, in particular
12-
https://spec.matrix.org/unstable/proposals/#process.
10+
https://spec.matrix.org/proposals/#process.
1311

14-
The Matrix specification itself is maintained at
12+
The source of the Matrix specification itself is maintained at
1513
https://github.com/matrix-org/matrix-spec.
14+
15+
## The Matrix Spec Process
16+
17+
An MSC is meant to be a **technical document that unambiguously describes a
18+
change to the Matrix Spec**, while also justifying _why_ the change should be
19+
made.
20+
21+
The document is used both to judge whether the change should be made as
22+
described *and* by developers to actually implement the changes. This is why
23+
it's important for an MSC to be fully fleshed out in technical detail, as once
24+
merged it's immediately part of the formal spec (even though it still needs to
25+
be transcribed into the actual spec itself).
26+
27+
### What changes need to follow this process?
28+
29+
In most cases a change to [the Matrix protocol](https://spec.matrix.org) will
30+
require an MSC. Changes that would not require an MSC are typically small and
31+
uncontentious, or are simply clarifications to the spec. Fixing typos in the
32+
spec do not require an MSC. In most cases, removing ambiguities do not either.
33+
The exception may be if implementations in the ecosystem have differing views
34+
on clarifying the ambiguity. In that case, an MSC is typically the best place
35+
to reach consensus.
36+
37+
Ultimately, the [Spec Core Team](https://matrix.org/foundation) have the final
38+
say on this, but generally if the change would require updates to a
39+
non-insignificant portion of the Matrix implementation ecosystem or would be
40+
met with contention, an MSC is the best route to take. You can also ask in the
41+
[Matrix Spec](https://matrix.to/#/#matrix-spec:matrix.org) or [Office of the
42+
Spec Core Team](https://matrix.to/#/#sct-office:matrix.org) Matrix rooms for
43+
clarification.
44+
45+
### Summary of the process
46+
47+
The MSC process consists of three basic steps:
48+
49+
1. **Write up the proposal** in a
50+
[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)
51+
document. (There's a [proposal
52+
template](proposals/0000-proposal-template.md), but don't feel bound by it.)
53+
2. **Submit it as a Pull Request** to this repo, marking it as a draft until
54+
it's ready for wider review.
55+
3. **Seek review** from the community. Once people are generally happy with it,
56+
ask the [Spec Core Team](https://matrix.org/foundation) to look at it in
57+
[the Office of the SCT Matrix
58+
room](https://matrix.to/#/#sct-office:matrix.org). When the SCT are happy
59+
with the proposal, and after a successful voting process, your pull request
60+
is merged and the **MSC is now officially accepted** as part of the Matrix
61+
Spec and can be used 🎉
62+
63+
For simple changes this is really all you need to know. For larger or more
64+
controversial changes, getting an MSC merged can take more time and effort, but
65+
the overall process remains the same.
66+
67+
Below is various guidance to try and help make the experience smoother.
68+
69+
### Guidance on the process
70+
71+
#### 1. Writing the proposal
72+
73+
Come up with an idea. The idea can be for anything, but the solution (MSC)
74+
needs to benefit the Matrix ecosystem rather than yourself (or your company)
75+
specifically. Sometimes this means that the solution needs to be more generic
76+
than the specific itch that you are trying to scratch.
77+
78+
Remember that an MSC is a formal technical document which will be used by
79+
others in the wider community to judge if the proposal should be accepted *and*
80+
to actually implement the changes in clients and servers. This means that for
81+
an MSC to be accepted it should include justifications and describe the
82+
technical changes unambiguously, including specifying what happens in any and
83+
all edge cases.
84+
85+
There's a [proposal template](proposals/0000-proposal-template.md) under
86+
`docs/0000-proposal.md`, but you don't necessarily need to use it. Covering the
87+
same major points is fine.
88+
* Note: At this stage, you won't have an MSC number, so feel free to use
89+
`0000`, `XXXX`, or whatever other placeholder you feel comfortable with.
90+
91+
Some tips for MSC writing:
92+
93+
* Please wrap your lines to 80 characters maximum (some small leeway is OK).
94+
This allows readers to review your markdown without needing to horizontally
95+
scroll back and forth. Many markdown text editors have this a feature.
96+
* If you are referencing an existing endpoint in the spec, or another MSC, it
97+
is very helpful to add a link to them so the reader does not need to search
98+
themselves. Examples:
99+
* "This MSC proposals an alternative to
100+
[MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030)."
101+
* "A new field will be added to the response body of
102+
[`/_matrix/client/v3/sync`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3sync)".
103+
* Note: it is best to link to the latest stable version of the spec
104+
(e.g. /v1.3, not /latest) - failing that,
105+
[/unstable](https://spec.matrix.org/unstable/) if the change is not
106+
yet in a released spec version.
107+
* GitHub supports rendering fancy diagrams from text with very little
108+
effort using [Mermaid](https://mermaid-js.github.io/mermaid/#/). See [this
109+
guide](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)
110+
for more information.
111+
112+
#### 2. Submitting a Pull Request
113+
114+
1. Open a [Pull
115+
Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
116+
to add your proposal document to the [`proposals`](proposals) directory.
117+
Note that this will require a GitHub account.
118+
* [Mark your Pull Request as a
119+
draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
120+
for now.
121+
2. The MSC number is the number of the pull request that is automatically
122+
assigned by GitHub. Go back through and edit the document accordingly. Don't
123+
forget the file name itself!
124+
3. Edit the pull request title to fit the format "MSC1234: Your proposal
125+
title".
126+
4. Once your proposal is correctly formatted and ready for review from the
127+
wider ecosystem, [take your Pull Request out of draft
128+
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).
129+
130+
The Spec Core Team will notice this and apply various labels/status tracking to
131+
your MSC, which will announce it to the wider world.
132+
133+
#### 3. Seeking review
134+
135+
Seek review from the Matrix community. Generally this will happen naturally,
136+
but if you feel that your proposal is lacking review then ask for people's
137+
opinion in the [Matrix Spec room on
138+
Matrix](https://matrix.to/#/#matrix-spec:matrix.org).
139+
140+
Reviews can take many forms, and do not need to be done solely by members of
141+
the Spec Core Team. Getting other people who are familiar with the area of
142+
Matrix you are proposing changes to is a great first step; especially those who
143+
may be implementing these changes in clients and/or homeservers.
144+
145+
While the proposal is a work in progress, it's fine for it to be high level
146+
and hand-wavy in places, but remember that before it can be accepted it needs
147+
to be expanded to fully flesh out all the technical detail and edge cases.
148+
149+
At this stage the proposal should also be implemented as a proof of concept
150+
somewhere to show that it _actually_ works in practice. This can be done on any
151+
client or server and doesn't need to be merged or released.
152+
153+
#### 4. Entering Final Comment Period
154+
155+
After the MSC has been implemented, fully fleshed out, and generally feels
156+
ready for final review, you should ask a member of the Spec Core Team to review it in
157+
the public [Spec Core Team Office room on
158+
Matrix](https://matrix.to/#/#sct-office:matrix.org). Someone from the SCT will
159+
then review it, and if all looks well will propose FCP
160+
to start.
161+
162+
At this point, other members of the SCT will look at the proposal and consider
163+
it for inclusion in the spec.
164+
165+
After enough SCT members have approved the proposal, the MSC will enter
166+
something called _Final Comment Period_. This is a 5 calendar day countdown to
167+
give anyone one last chance to raise any blockers or concerns about the
168+
proposed change. Typically MSCs pass this stage without incident, but it
169+
nevertheless serves as a safeguard.
170+
171+
#### 5. The MSC is accepted
172+
173+
Once FCP has ended and the MSC pull request is merged, the proposed change is
174+
considered officially part of the spec. Congratulations!
175+
176+
Clients and servers can now start using the change, even though at this stage
177+
it still needs to be transcribed into the spec document. This happens over in
178+
https://github.com/matrix-org/matrix-spec/ and is typically handled by the Spec
179+
Core Team themselves.
180+
181+
### Other useful information
182+
183+
#### Unstable prefixes
184+
185+
*Unstable* prefixes are the namespaces which are used before an MSC has
186+
completed FCP (see above). While the MSC might propose that a `m.space` or
187+
`/_matrix/client/v1/account/whoami` endpoint should exist, the implementation
188+
cannot use a *stable* identifier such as `/v1/` or `m.space` prior to the MSC
189+
being accepted: it needs unstable prefixes.
190+
191+
Typically for MSCs, one will use `org.matrix.msc0000` (using the real MSC
192+
number once known) as a prefix. For the above examples, this would mean
193+
`org.matrix.msc0000.space` and
194+
`/_matrix/client/unstable/org.matrix.msc0000/account/whoami` to allow for
195+
breaking compatibility changes between edits of the MSC itself, or indeed
196+
another competing MSC that's attempting to add the same identifiers.
197+
198+
199+
#### Room versions
200+
201+
To summarize [the spec](https://spec.matrix.org/latest/rooms/) on room
202+
versions: they are how servers agree upon algorithms in a decentralized world
203+
like ours. Examples of changes that require a new room version include anything that changes:
204+
* The format of the core event structure (such as renaming a top-level field,
205+
or modifying [the redaction
206+
algorithm](https://spec.matrix.org/latest/client-server-api/#redactions)),
207+
therefore altering the [reference
208+
hash](https://spec.matrix.org/latest/server-server-api/#calculating-the-reference-hash-for-an-event)
209+
of an event.
210+
* [The authorisation of
211+
events](https://spec.matrix.org/latest/server-server-api/#authorization-rules)
212+
(such as changes to power levels).
213+
214+
Unstable prefixes (see above) for room versions work the same as they do for
215+
other identifiers; your unstable room version may be called
216+
"org.matrix.msc1234".
217+
218+
In order for the changes to end up in a "real" room version (the ones listed in
219+
the spec), it will need a second MSC which aggregates a bunch of functionality
220+
from various MSCs into a single room version. Typically these sorts of curating
221+
MSCs are written by the Spec Core Team given the complexity in wording, but
222+
you're more than welcome to bring an MSC forward which makes the version real.
223+
224+
For an example of what introducing a new room version-required feature can look
225+
like, see [MSC3667](https://github.com/matrix-org/matrix-doc/pull/3667). For an
226+
example of what making a new "real" room version looks like, see
227+
[MSC3604](https://github.com/matrix-org/matrix-doc/pull/3604).
228+
229+
#### Ownership of MSCs and closing them
230+
231+
If an author decides that they would no longer like to pursue their MSC, they
232+
can either pass ownership of it off to someone else, or close it themselves.
233+
234+
* The author of an MSC can close their MSC at any time before FCP by simply
235+
closing the pull request.
236+
* To appoint another user as an author of the MSC (either to replace the author
237+
entirely or to provide additional help), make a note in the MSC's PR
238+
description by writing the following on its own line:
239+
240+
```
241+
Author: @username
242+
```
243+
244+
where `@username` is a valid GitHub username. Multiple such lines can be
245+
added.
246+
247+
Finally, [give that user access to write to your fork of
248+
matrix-spec-proposals on
249+
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),
250+
which your PR originates from. This will allow them to change the text of
251+
your MSC.
252+
253+
Similar to accepting an MSC, the Spec Core Team may propose a Final Comment
254+
Period with a disposition of "close". This can happen if the MSC appears
255+
abandoned by its author, or the idea is widely rejected by the community. A
256+
vote and final comment period will still be required for the motion to pass.
257+
258+
Additionally, FCP can be also proposed with a disposition of "postpone". This
259+
may be done for MSCs for which the proposed changes do not make sense for the
260+
current state of the ecosystem, but may make sense further down the road.
261+
262+
## Asking for help
263+
264+
The Matrix community and members of the Spec Core Team are here to help guide
265+
you through the process!
266+
267+
If you'd just like to get initial feedback about an idea that's not fully
268+
fleshed out yet, creating an issue at
269+
https://github.com/matrix-org/matrix-spec/issues is a great place to start. Be
270+
sure to search for any existing issues first to see if someone has already had
271+
the same idea!
272+
273+
A few official rooms exist on Matrix where your questions can be answered, or
274+
feedback on your proposal can be requested:
275+
276+
* [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) -
277+
General chat for MSCs, the spec, and pretty much anything in that sphere.
278+
* [#sct-office:matrix.org](https://matrix.to/#/#sct-office:matrix.org) - Where
279+
the Spec Core Team hangs out and is available. This room is intended to have
280+
extremely high signal and low noise, primarily to ensure that MSCs are not
281+
falling through the cracks. If an MSC requires attention or comment from Spec
282+
Core Team members, bring it up here.
283+
* [#matrix-spec-process:matrix.org](https://matrix.to/#/#matrix-spec-process:matrix.org) - A
284+
room dedicated to [the spec process
285+
itself](https://spec.matrix.org/proposals/#process). If you have any
286+
questions about or suggestions to improve the Matrix Spec process, ask them
287+
here.
288+
* [#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) - A
289+
quieter room for discussion of the [formal spec
290+
text](https://spec.matrix.org) and [matrix.org](https://matrix.org) website.

0 commit comments

Comments
 (0)