Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the README with details on the Matrix spec process + unstable prefixes #3891

Merged
merged 12 commits into from
Sep 28, 2022
Merged

Update the README with details on the Matrix spec process + unstable prefixes #3891

Changes from 8 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
806d1b6
Update the README with details on the process/unstable prefixes
anoadragon453 Sep 14, 2022
f910918
Link to the README from the contributing guide
anoadragon453 Sep 14, 2022
3dd365b
Spell out which changes would generally require an MSC
anoadragon453 Sep 27, 2022
349075f
Add MSC writing tips section
anoadragon453 Sep 27, 2022
7138dce
Suggestion using draft PRs instead of 'WIP:'
anoadragon453 Sep 27, 2022
261000b
Fix hierarchy of headers
anoadragon453 Sep 27, 2022
9f93f54
Improve examples of proposals that require a new room version
anoadragon453 Sep 27, 2022
d814ed2
Reduce the number of steps in the process summary
anoadragon453 Sep 27, 2022
e97b079
Update README.md
anoadragon453 Sep 27, 2022
4a9ef61
Clean up the room version tips section a bit
anoadragon453 Sep 27, 2022
53bde44
Move redaction algorithm back to an example of event hash changes
anoadragon453 Sep 28, 2022
21ce2ea
Fix missing newline
anoadragon453 Sep 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 91 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ 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
Expand All @@ -25,35 +24,51 @@ 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).

The MSC process consists of five basic steps:
### 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, adding "WIP" to the title if
it's still a work in progress.
3. **Seek review** from the community. Once people are happy
with it, ask the [Spec Core Team](https://matrix.org/foundation) (SCT) to
look at it in
[the SCT office Matrix room](https://matrix.to/#/#sct-office:matrix.org).
4. When the SCT are happy with the proposal, they'll vote for its acceptance.
The proposal will go into a **Final Comment Period (FCP)**, which gives
everyone the chance to raise any concerns.
5. After 5 days has passed, assuming no major issues have arisen, your pull
request is merged and the **MSC is now officially accepted** as part of the
Matrix Spec and can be used 🎉
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

#### Step 1: Writing up the proposal
#### 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)
Expand All @@ -73,23 +88,49 @@ 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.

#### Step 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)
Some tips for MSC writing:

* Please wrap your lines to 80 characters maximum (some small leeway is OK).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Contradicts instructions in the specification repository

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, and looking at comments from the SCT on various MSCs (1, 2, 3), we're happy to either have a wrap at 80 or 120 characters. So let's go for 120 as a suggested maximum.

This allows readers to review your markdown without needing to horizontally
scroll back and forth. Many markdown text editors have this a 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.

#### 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". If it's still a work in progress, put "WIP" somewhere in the title
(usually the beginning).
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.

#### Step 3: Seeking review
#### 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
Expand All @@ -109,13 +150,13 @@ 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.

#### Step 4: Entering Final Comment Period
#### 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 _Final Comment Period_ (FCP)
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
Expand All @@ -127,11 +168,10 @@ 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

#### Step 5: MSC is accepted

Once FCP has end and the MSC pull request merged, the proposed change
is considered officially part of the spec. Congratulations!
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
Expand All @@ -140,7 +180,7 @@ Core Team themselves.

### Other useful information

## Unstable prefixes
#### Unstable prefixes

*Unstable* prefixes are the namespaces which are used before an MSC has
completed FCP (see above). While the MSC might propose that a `m.space` or
Expand All @@ -156,36 +196,37 @@ breaking compatibility changes between edits of the MSC itself, or indeed
another competing MSC that's attempting to add the same identifiers.


## Room versions
#### 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. Typically, anything which touches _how_ power levels, authorization
of events, and redaction works will need a new room version. If your proposal
changes how any of these algorithms work, then it must specify that a new room
version is needed. Unstable prefixes (see above) work the same for room
versions as they do for other identifiers; for example your room version may
simply be called `org.matrix.msc0000`.
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),
as this will change 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).
* [the redaction
algorithm](https://spec.matrix.org/latest/client-server-api/#redactions).
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

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 varying MSCs into a single room version. Typically these sorts of curating
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.

Note that your MSC *should not* declare the stable room version it gets
included in - it should simply specify the need for a new room version as well
as the unstable identifier. Even after your MSC is accepted, your change will
remain as part of a prefixed room version until a second room version MSC is
accepted.

For a relatively simple example of what introducing a new room version-required
feature can look like, see
[MSC3613](https://github.com/matrix-org/matrix-doc/pull/3613). For an example
of what making a new "real" room version looks like, see
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
#### 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.
Expand Down Expand Up @@ -218,7 +259,7 @@ 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
## Asking for help

The Matrix community and members of the Spec Core Team are here to help guide
you through the process!
Expand Down