wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1697 from matrix-org/anoa/msc_update

Browse source 
The new and improved MSC process
This commit is contained in:
Andrew Morgan 2018-10-23 20:02:36 +02:00 • committed by GitHub
commit f288facec8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 325 additions and 156 deletions
Download patch file Download diff file Expand all files Collapse all files

113
proposals/0000-proposal-template.md Normal file
View file

@ -0,0 +1,113 @@
# Example: Proposal to adopt a template for MSCs
*Note: Text written in italics represents notes about the section or proposal process. This document
serves as an example of what a proposal could look like (in this case, a proposal to have a template)
and should be used where possible.*
*In this first section, be sure to cover your problem and a broad overview of the solution. Covering
related details, such as the expected impact, can also be a good idea. The example in this document
says that we're missing a template and that things are confusing and goes on to say the solution is
a template. There's no major expected impact in this proposal, so it doesn't list one. If your proposal
was more invasive (such as proposing a change to how servers discover each other) then that would be
a good thing to list here.*
*If you're having troubles coming up with a description, a good question to ask is "how
does this proposal improve Matrix?" - the answer could reveal a small impact, and that is okay.*
There can never be enough templates in the world, and MSCs shouldn't be any different. The level
of detail expected of proposals can be unclear - this is what this example proposal (which doubles
as a template itself) aims to resolve.
## Proposal
*Here is where you'll reinforce your position from the introduction in more detail, as well as cover
the technical points of your proposal. Including rationale for your proposed solution and detailing
why parts are important helps reviewers understand the problem at hand. Not including enough detail
can result in people guessing, leading to confusing arguments in the comments section. The example
here covers why templates are important again, giving a stronger argument as to why we should have
a template. Afterwards, it goes on to cover the specifics of what the template could look like.*
Having a default template that everyone can use is important. Without a template, proposals would be
all over the place and the minimum amount of detail may be left out. Introducing a template to the
proposal process helps ensure that some amount of consistency is present across multiple proposals,
even if each author decides to abandon the template.
The default template should be a markdown document because the MSC process requires authors to write
a proposal in markdown. Using other formats wouldn't make much sense because that would prevent authors
from copy/pasting the template.
The template should have the following sections:
* **Introduction** - This should cover the primary problem and broad description of the solution.
* **Proposal** - The gory details of the proposal.
* **Tradeoffs** - Any items of the proposal that are less desirable should be listed here. Alternative
solutions to the same problem could also be listed here.
* **Potential issues** - This is where problems with the proposal would be listed, such as changes
that are not backwards compatible.
* **Security considerations** - Discussion of what steps were taken to avoid security issues in the
future and any potential risks in the proposal.
* **Conclusion** - A repeat of the problem and solution.
Furthermore, the template should not be required to be followed. However it is strongly recommended to
maintain some sense of consistency between proposals.
## Tradeoffs
*This is where alternative solutions could be listed. There's almost always another way to do things
and this section gives you the opportunity to highlight why those ways are not as desirable. The
argument made in this example is that all of the text provided by the template could be integrated
into the proposals introduction, although with some risk of losing clarity.*
Instead of adding a template to the repository, the assistance it provides could be integrated into
the proposal process itself. There is an argument to be had that the proposal process should be as
descriptive as possible, although having even more detail in the proposals introduction could lead to
some confusion or lack of understanding. Not to mention if the document is too large then potential
authors could be scared off as the process suddenly looks a lot more complicated than it is. For those
reasons, this proposal does not consider integrating the template in the proposals introduction a good
idea.
## Potential issues
*Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal,
and they should be documented here. There should be some explanation for why the disadvantage is
acceptable, however - just like in this example.*
Someone is going to have to spend the time to figure out what the template should actually have in it.
It could be a document with just a few headers or a supplementary document to the process explanation,
however more detail should be included. A template that actually proposes something should be considered
because it not only gives an opportunity to show what a basic proposal looks like, it also means that
explanations for each section can be described. Spending the time to work out the content of the template
is beneficial and not considered a significant problem because it will lead to a document that everyone
can follow.
# Security considerations
*Some proposals may have some security aspect to them that was addressed in the proposed solution. This
section is a great place to outline some of the security-sensitive components of your proposal, such as
why a particular approach was (or wasn't) taken. The example here is a bit of a stretch and unlikely to
actually be worthwhile of including in a proposal, but it is generally a good idea to list these kinds
of concerns where possible.*
By having a template available, people would know what the desired detail for a proposal is. This is not
considered a risk because it is important that people understand the proposal process from start to end.
## Conclusion
*Repeating the problem and solution in different words helps reviewers understand the problem a bit more.
This section should wrap up any loose ends left in the document, as well as cover a brief overview of the
content in each section. Note that the example here doesn't touch on the specific implementation details
described in the "Proposal" section - just the high-level points made there.*
Not having a template for people to follow when making their proposals could lead to large differences
between each MSC. This would make it difficult for reviewers, and there's a potential that some information
could be left out by accident. A template written in the same format the proposal process requires would
give authors the ability to understand how to better explain their own proposal.
A descriptive template would help potential authors comprehend what the proposal process requires by
demonstrating what is expected of a proposal. Although this is more effort up front, it would lead to more
time saved in the future due to questions about the process.

352
specification/proposals_intro.rst
View file

@ -6,97 +6,52 @@
Proposals for Spec Changes to Matrix Proposals for Spec Changes to Matrix
------------------------------------ ------------------------------------
The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: If you are interested in submitting a change to the Matrix Specification,
please take note of the following guidelines.
- Produce a publicly-accessible proposal describing your change: All changes to Specification content require a formal proposal process. This
involves writing a proposal, having it reviewed by everyone, having the
proposal being accepted, then actually having your ideas implemented as
committed changes to the `Specification repository
<https://github.com/matrix-org/matrix-doc>`_.
- Please use Google Docs, or an equivalent system capable of collaborative Meet the `members of the Core Team
editing, with versioned history, suggestions ('track changes'), threaded <https://github.com/orgs/matrix-org/teams/spec-core-team/members>`_, a group of
comments, and good mobile support. Please ensure the document is individuals tasked with ensuring the spec process is as smooth and painless as
world-commentable or -editable. possible. Members of the Core Team will do their best to participate in
- We do not use Github issues (or Etherpad) for the design process of the discussion, summarise when things become long-winded, and generally try to act
proposal, as the document review/commenting capabilities aren't good towards the benefit of everyone. As a majority, team members have the ability
enough. to change the state of a proposal, and individually have the final say in
- We also don't jump straight to PRing against the spec itself, as it's much proposal discussion.
faster to iterate on a proposal in freeform document form than in the
terse and formal structure of the spec.
- In the proposal, please clearly state the problem being solved, and the
possible solutions being proposed for solving it and their respective
trade-offs.
- Proposal documents are intended to be as lightweight and flexible as the
author desires; there is no formal template; the intention is to iterate
as quickly as possible to get to a good design.
- A `template with suggested headers
<https://docs.google.com/document/d/1CoLCPTcRFvD4PqjvbUl3ZIWgGLpmRNbqxsT2Tu7lCzI/>`_
is available.
- Make a new issue at https://github.com/matrix-org/matrix-doc/issues, whose Guiding Principles
description should list the metadata as per below. Use the github search ------------------
function to attempt to locate any related github issues, and link any that
are found in the body of the new issue.
- Gather feedback as widely as possible from the community and core team on
the proposal.
- The aim is to get maximum consensus on the trade-offs chosen to get an
optimal solution.
- A good place to ask for feedback on a specific proposal is
`#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_.
However, authors/shepherds are welcome to use an alternative room if they
prefer - please advertise it in #matrix-spec:matrix.org though and link
to it on the github issue. N.B. that #matrix-dev:matrix.org is for
developers using existing Matrix APIs, #matrix:matrix.org is for users
trying to run matrix apps (clients & servers);
#matrix-architecture:matrix.org is for cross-cutting discussion of
Matrix's architectural design.
- The point of the spec proposal process is to be collaborative rather than
competitive, and to try to solve the problem in question with the optimal
set of trade-offs. Ideally the author would neutrally gather the various
viewpoints and get consensus, but this can sometimes be time-consuming (or
the author may be biased), in which case an impartial 'shepherd' can be
assigned to help guide the proposal through this process. A shepherd is
typically a neutral party from the core team or an experienced member of
the community.
- Once the proposal has sufficient consensus and passed review, you **must**
show an implementation to prove that it works well in practice, before a
spec PR will be accepted. Iterate on the proposal if needed.
- Finally, please make a new spec PR which includes the changes as
implemented against
https://github.com/matrix-org/matrix-doc/tree/master/specification. This
will then be reviewed and hopefully merged! Please sign off the spec PR as
per the `CONTRIBUTING.rst
<https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_
guidelines.
Final decisions on review are made by the Matrix core team
(+matrix:matrix.org), acting on behalf of the whole Matrix community.
Proposals **must** act to the greater benefit of the entire Matrix ecosystem, Proposals **must** act to the greater benefit of the entire Matrix ecosystem,
rather than benefiting or privileging any single player or subset of players rather than benefiting or privileging any single player or subset of players -
- and must not contain any patent encumbered IP. The Matrix core team pledges and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as
to act as a neutral custodian for Matrix on behalf of the whole ecosystem, a neutral custodian for Matrix on behalf of the whole ecosystem.
just as it has since Matrix's inception in May 2014.
For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That
includes client users, server admins, client developers, bot developers, includes client users, server admins, client developers, bot developers,
bridge and AS developers, users and admins who are indirectly using Matrix via bridge and application service developers, users and admins who are indirectly using Matrix via
3rd party networks which happen to be bridged, server developers, room 3rd party networks which happen to be bridged, server developers, room
moderators and admins, companies/projects building products or services on moderators and admins, companies/projects building products or services on
Matrix, spec contributors, translators, and the core team who created it in Matrix, spec contributors, translators, and those who created it in
the first place. the first place.
"Greater benefit" could include maximising: "Greater benefit" could include maximising:
* the number of end-users reachable on the open Matrix network. * the number of end-users reachable on the open Matrix network
* the number of regular users on the Matrix network (e.g. 30-day retained * the number of regular users on the Matrix network (e.g. 30-day retained
federated users) federated users)
* the number of online servers in the open federation. * the number of online servers in the open federation
* the number of developers building on Matrix. * the number of developers building on Matrix
* the number of independent implementations which use Matrix * the number of independent implementations which use Matrix
* the quality and utility of the Matrix spec. * the quality and utility of the Matrix spec
The guiding principles of the overall project are being worked on as part of In addition, proposal authors are expected to uphold the following values in
the upcoming governance proposal, but could be something like: their proposed changes to the Matrix protocol:
* Supporting the whole long-term ecosystem rather than individual stakeholder gain * Supporting the whole long-term ecosystem rather than individual stakeholder gain
* Openness rather than proprietariness * Openness rather than proprietariness
@ -107,107 +62,208 @@ the upcoming governance proposal, but could be something like:
* Pragmatism rather than perfection * Pragmatism rather than perfection
* Proof rather than conjecture * Proof rather than conjecture
The above directions are intended to be simple and pragmatic rather than Process
exhaustive, and aim to provide guidelines until we have a formal spec -------
governance process in place that covers the whole Matrix community. In order
to get Matrix out of beta as quickly as possible, as of May 2018 we are
prioritising spec and reference implementation development over writing formal
governance, but a formal governance document will follow as rapidly as
possible.
The process for handling proposals is described in the following diagram. Note The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as
that the lifetime of a proposal is tracked through the corresponding labels for follows:
each stage in the `matrix-doc issue tracker
<https://github.com/matrix-org/matrix-doc/issues>`_. - Create a first draft of your proposal using `GitHub-flavored markdown
<https://help.github.com/articles/basic-writing-and-formatting-syntax/>`_
- In the document, clearly state the problem being solved, and the possible
solutions being proposed for solving it and their respective trade-offs.
- Proposal documents are intended to be as lightweight and flexible as the
author desires; there is no formal template; the intention is to iterate
as quickly as possible to get to a good design.
- However, a `template with suggested headers
<https://github.com/matrix-org/matrix-doc/blob/master/proposals/0000-proposal-template.md>`_
is available to get you started if necessary.
- Take care in creating your proposal. Specify your intended changes, and
give reasoning to back them up. Changes without justification will likely
be poorly received by the community.
- Fork and make a PR to the `matrix-doc
<https://github.com/matrix-org/matrix-doc>`_ repository. The ID of your PR
will become the MSC ID for the lifetime of your proposal.
- The proposal must live in the ``proposals/`` directory with a filename that
follows the format ``1234-my-new-proposal.md`` where ``1234`` is the MSC
ID.
- Your PR description must include a link to the rendered markdown document
and a summary of the proposal.
- It is often very helpful to link any related MSCs or `matrix-doc issues
<https://github.com/matrix-org/matrix-doc/issues>`_ to give context
for the proposal.
- Additionally, please be sure to sign off your proposal PR as per the
guidelines listed on `CONTRIBUTING.rst
<https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_.
- Gather feedback as widely as possible.
- The aim is to get maximum consensus towards an optimal solution. Sometimes
trade-offs are required to meet this goal. Decisions should be made to the
benefit of all major use cases.
- A good place to ask for feedback on a specific proposal is
`#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_.
If preferred, an alternative room can be created and advertised in
#matrix-spec:matrix.org. Please also link to the room in your PR
description.
- For additional discussion areas, know that that #matrix-dev:matrix.org is
for developers using existing Matrix APIs, #matrix:matrix.org is for users
trying to run Matrix apps (clients & servers) and
#matrix-architecture:matrix.org is for cross-cutting discussion of matrix's
architectural design.
- The point of the spec proposal process is to be collaborative rather than
competitive, and to try to solve the problem in question with the optimal
set of trade-offs. The author should neutrally gather the various
viewpoints and get consensus, but this can sometimes be time-consuming (or
the author may be biased), in which case an impartial 'shepherd' can be
assigned to help guide the proposal through this process. A shepherd is
typically a neutral party from the Core Team or an experienced member of
the community. There is no formal process for assignment. Simply ask for a
shepherd to help get your proposal through and one will be assigned based
on availability. Having a shepherd is not a requirement for proposal
acceptance.
- Members of the Core Team and community will review and discuss the PR in the
comments and in relevant rooms on Matrix. Discussion outside of GitHub should
be summarised in a comment on the PR.
- When a member of the Core Team believes that no new discussion points are
being made, they will propose a motion for a final comment period (FCP),
along with a *disposition* of either merge, close or postpone. This FCP is
provided to allow a short period of time for any invested party to provide a
final objection before a major decision is made. If sufficient reasoning is
given, an FCP can be cancelled. It is often preceded by a comment summarising
the current state of the discussion, along with reasoning for its occurrence.
- A concern can be raised by a Core Team member at any time, which will block
an FCP from beginning. An FCP will only begin when a **majority** of core
team members agree on its outcome, and all existing concerns have been
resolved.
- The FCP will then begin and last for 5 days, giving anyone else some time to
speak up before it concludes. On its conclusion, the disposition of the FCP
will be carried out. If sufficient reasoning against the disposition is
raised, the FCP can be cancelled and the MSC will continue to evolve
accordingly.
- Once the proposal has been accepted and merged, it is time to submit the
actual change to the Specification that your proposal reasoned about. This is
known as a spec PR. However in order for the spec PR to be accepted, an
implementation **must** be shown to prove that it works well in practice. A
link to the implementation should be included in the PR description. In
addition, any significant unforeseen changes to the original idea found
during this process will warrant another MSC. Any minor, non-fundamental
changes are allowed but **must** be documented in the original proposal
document. This ensures that someone reading a proposal in the future doesn't
assume old information wasn't merged into the spec.
- Similar to the proposal PR, please sign off the spec PR as per the
guidelines on `CONTRIBUTING.rst
<https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_.
- Your PR will then be reviewed and hopefully merged on the grounds it is
implemented sufficiently. If so, then give yourself a pat on the back knowing
you've contributed to the Matrix protocol for the benefit of users and
developers alike :)
The process for handling proposals is shown visually in the following diagram.
Note that the lifetime of a proposal is tracked through the corresponding
labels for each stage on the `matrix-doc
<https://github.com/matrix-org/matrix-doc>`_ issue and pull request trackers.
:: ::
+ + + +
Proposals | Spec PRs | Other States Proposals | Spec PRs | Additional States
+-------+ | +------+ | +----------+ +-------+ | +------+ | +---------------+
| | | |
| | +----------------------+ | +---------+ | +-----------+
+----------+ | +---------+ | +---------+
| | | | | | | | | | | | | | | |
| Proposal | | +------> Spec PR | | | Blocked | | Proposal | | +------= Spec PR | | | Postponed |
| WIP | | | | Missing | | | | | Drafting and Initial | | | | Missing | | | |
| | | | | | | +---------+ | Feedback Gathering | | | | | | +-----------+
+----+-----+ | | +----+----+ | | | | | +----+----+ |
| | | | | +----------+-----------+ | | | | +----------+
| | | | | +-----------+ | | | v | | |
+--------v----------+ | | | | | | v | | +-----------------+ | | Closed |
| | | | +---------v--------+ | | Abandoned | +-------------------+ | | | | | | |
| Proposal | | | | | | | | | | | | | Spec PR Created | | +----------+
| Ready for Review | | | | Spec PR | | +-----------+ | Proposal PR | | | | and In Review | |
| | | | | Ready for Review | | | Created and | | | | | |
+----------+--------+ | | | | | +-----------+ | In Review | | | +--------+--------+ |
| | | +---------+--------+ | | |
| | | | | | Obsolete |
+------v----+ | | | | | |
| | | | +-----v-----+ | +-----------+
| Proposal | | | | | |
| In Review | | | | Spec PR | |
| | | | | In Review | | +----------+
+----+------+ | | | | | | |
| | | +-----+-----+ | | Rejected |
| | | | | | |
+------v--------+ | | | | +----------+
| | | | | | | | | | | |
| Proposal | | | +----v----+ | +---------+---------+ | | v |
| Passed Review | | | | | | | | | +-----------+ |
v | | | | |
+----------------------+ | | | Spec PR | |
| | | | | Merged! | | | | | | | Merged! | |
+-------+-------+ | | | | | | Final Comment Period | | | | | |
| | | +---------+ | | | | | +-----------+ |
+----------+-----------+ | | |
| | | | | | | |
+---------------+ | v | | |
+-------------+ | | |
| | | | |
| Proposal PR | | | |
| Merged! | | | |
| | | | |
+------|------+ | | |
| | | |
+-----------------+ |
| | | |
+ + + +
Lifetime States Lifetime States
--------------- ---------------
=========================== ======================================================= **Note:** All labels are to be placed on the proposal PR.
Proposal WIP A proposal document which is still work-in-progress but is being shared to incorporate feedback
Proposal Ready for Review A proposal document which is now ready and waiting for review by the core team and community =============================== ============================= ====================================
Proposal In Review A proposal document which is currently in review Name GitHub Label Description
Proposal Passed Review A proposal document which has passed review as worth implementing and then being added to the spec =============================== ============================= ====================================
Spec PR Missing A proposal which has been implemented and has been used in the wild for a few months but hasn't yet been added to the spec Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback
Spec PR Ready for Review A proposal which has been PR'd against the spec and is awaiting review Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Core Team and community
Spec PR In Review A proposal which has been PR'd against the spec and is in review Proposal Final Comment Period proposal-final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement
Merged A proposal whose PR has merged into the spec! Proposal Merged/Spec PR Missing spec-pr-missing A proposal document which has passed review. Waiting for a PR against the Spec
Blocked A proposal which is temporarily blocked on some external factor (e.g. being blocked on another proposal first being approved) Spec PR In Review spec-pr-in-review A proposal that has been PR'd against the spec and is currently under review
Abandoned A proposal where the author/shepherd has not been responsive for a few months Spec PR Merged merged A proposal with a sufficient working implementation and whose Spec PR has been merged!
Obsolete A proposal which has been overtaken by other proposals Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps
Rejected A proposal which is not going to be incorporated into Matrix sometime in the future
=========================== ======================================================= Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance
=============================== ============================= ====================================
Proposal Tracking Proposal Tracking
----------------- -----------------
This is a living document generated from the list of proposals at This is a living document generated from the list of proposals on the issue and
`matrix-doc/issues <https://github.com/matrix-org/matrix-doc/issues>`_ on pull request trackers of the `matrix-doc
GitHub. <https://github.com/matrix-org/matrix-doc>`_ repo.
We use labels and some metadata in the issues' descriptions to generate this We use labels and some metadata in MSC PR descriptions to generate this page.
page. Labels are assigned by the core team whilst triaging the issues based Labels are assigned by the Core Team whilst triaging the proposals based on those
on those which exist in the matrix-doc repo already. which exist in the `matrix-doc <https://github.com/matrix-org/matrix-doc>`_
repo already.
It is worth mentioning that a previous version of the MSC process used a
mixture of GitHub issues and PRs, leading to some MSC numbers deriving from
GitHub issue IDs instead. A useful feature of GitHub is that it does
automatically resolve to an issue, if an issue ID is placed in a pull URL. This
means that https://github.com/matrix-org/matrix-doc/pull/$MSCID will correctly
resolve to the desired MSC, whether it started as an issue or a PR.
Other metadata: Other metadata:
- the MSC (Matrix Spec Change) number is taken from the github issue ID. This - The MSC number is taken from the GitHub Pull Request ID. This is carried for
is carried for the lifetime of the proposal, including the PR creation the lifetime of the proposal. These IDs do not necessary represent a
phase. N.B. They are not in chronological order! chronological order.
- Please use the github issue title to set the title. - The GitHub PR title will act as the MSC's title.
- Please link to the proposal document by adding a "Documentation: <url>" line
in the issue description.
- Please link to the spec PR (if any) by adding a "PRs: #1234" line in the - Please link to the spec PR (if any) by adding a "PRs: #1234" line in the
issue description. issue description.
- The creation date is taken from the github issue, but can be overriden by - The creation date is taken from the GitHub PR, but can be overridden by
adding a "Date: yyyy-mm-dd" line in the issue description. adding a "Date: yyyy-mm-dd" line in the PR description.
- Updated Date is taken from github. - Updated Date is taken from GitHub.
- Author is the creator of the github issue, but can be overriden by adding a - Author is the creator of the MSC PR, but can be overridden by adding a
"Author: @username" line in the body of the issue description. Please make "Author: @username" line in the body of the issue description. Please make
sure @username is a github user (include the @!) sure @username is a GitHub user (include the @!)
- A shepherd can be assigned by adding a "Shepherd: @username" line in the - A shepherd can be assigned by adding a "Shepherd: @username" line in the
issue description. Again, make sure this is a real Github user. issue description. Again, make sure this is a real GitHub user.