matrix-spec-proposals

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