archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Move to the new and improved MSC process

Browse Source
pull/1697/head
Andrew Morgan 7 years ago
parent db4de5022b
commit a3144e6959
1 changed files with 142 additions and 113 deletions
Show Stats Download Patch File Download Diff File

257
specification/proposals_intro.rst
Unescape Escape View File

@ -6,70 +6,98 @@
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:
Community changes to the specification require a formal proposal process. This
- Please use Google Docs, or an equivalent system capable of collaborative involves writing a proposal, having it reviewed by the matrix community, having
editing, with versioned history, suggestions ('track changes'), threaded the proposal being accepted, then actually having your ideas implemented as
comments, and good mobile support. Please ensure the document is committed changes to the `specification repository
world-commentable or -editable. <https://github.com/matrix-org/matrix-doc>`_.
- We do not use Github issues (or Etherpad) for the design process of the
proposal, as the document review/commenting capabilities aren't good The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as
enough. follows:
- We also don't jump straight to PRing against the spec itself, as it's much
faster to iterate on a proposal in freeform document form than in the - Create a first-draft of your proposal using `github-flavored markdown
terse and formal structure of the spec. <https://help.github.com/articles/basic-writing-and-formatting-syntax/>`_
- In the proposal, please clearly state the problem being solved, and the
possible solutions being proposed for solving it and their respective - In the document, clearly state the problem being solved, and the possible
trade-offs. solutions being proposed for solving it and their respective trade-offs.
- Proposal documents are intended to be as lightweight and flexible as the - Proposal documents are intended to be as lightweight and flexible as the
author desires; there is no formal template; the intention is to iterate author desires; there is no formal template; the intention is to iterate
as quickly as possible to get to a good design. as quickly as possible to get to a good design.
- A `template with suggested headers - However, a `template with suggested headers
<https://docs.google.com/document/d/1CoLCPTcRFvD4PqjvbUl3ZIWgGLpmRNbqxsT2Tu7lCzI/>`_ <https://docs.google.com/document/d/1CoLCPTcRFvD4PqjvbUl3ZIWgGLpmRNbqxsT2Tu7lCzI/>`_
is available. 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.
- 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 your proposal.
- Make a new issue at https://github.com/matrix-org/matrix-doc/issues, whose - Gather feedback as widely as possible from the community and core team.
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 - The aim is to get maximum consensus towards an optimal solution. Sometimes
optimal solution. 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 - A good place to ask for feedback on a specific proposal is
`#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_. `#matrix-spec:matrix.org <https://matrix.to/#/#matrix-spec:matrix.org>`_.
However, authors/shepherds are welcome to use an alternative room if they However, it is welcome to use an alternative room if preferred please
prefer - please advertise it in #matrix-spec:matrix.org though and link advertise it in #matrix-spec:matrix.org and link to it on the PR for
to it on the github issue. N.B. that #matrix-dev:matrix.org is for visibility.
developers using existing Matrix APIs, #matrix:matrix.org is for users - For additional discussion areas, know that that #matrix-dev:matrix.org is
trying to run matrix apps (clients & servers); for developers using existing Matrix APIs, #matrix:matrix.org is for users
#matrix-architecture:matrix.org is for cross-cutting discussion of trying to run matrix apps (clients & servers) and
Matrix's architectural design. #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 - 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 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 set of trade-offs. The author should neutrally gather the various
viewpoints and get consensus, but this can sometimes be time-consuming (or 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 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 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 typically a neutral party from the core team or an experienced member of
the community. the community. Having a shepherd is not a requirement for proposal
acceptance.
- Once the proposal has sufficient consensus and passed review, you **must**
show an implementation to prove that it works well in practice, before a - Members of the core team will review and discuss the PR in the comments and
spec PR will be accepted. Iterate on the proposal if needed. in relevant rooms on matrix. Discussion outside of Github should be
- Finally, please make a new spec PR which includes the changes as summarised in a comment on the PR.
implemented against - At some point a member of the core team will propose a motion for a final
https://github.com/matrix-org/matrix-doc/tree/master/specification. This comment period (FCP) with a *disposition* of merge, close or postpone. This
will then be reviewed and hopefully merged! Please sign off the spec PR as is usually preceded with a comment summarising the current state of the
per the `CONTRIBUTING.rst discussion, along with reasoning for the motion.
- A concern can be raised by a core team member at any time, which will block
the FCP from beginning. An FCP will only be 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, however, sufficient reasoning for the FCP not to
conclude is raised, the FCP can be cancelled and the MSC will continue to
evolve accordingly.
- Once your 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 your spec PR to be accepted, you
**must** show an implementation to prove that it works well in practice. In
addition, any significant unforeseen changes to the original idea found
during this process will warrant another MSC.
- Please sign off the spec PR as per the `CONTRIBUTING.rst
<https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_ <https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst>`_
guidelines. guidelines.
Final decisions on review are made by the Matrix core team - Your PR will then be reviewed and hopefully merged on the grounds it is
(+matrix:matrix.org), acting on behalf of the whole Matrix community. 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 :)
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
@ -122,64 +150,67 @@ each stage in the `matrix-doc issue tracker
:: ::
+ + + +
Proposals | Spec PRs | Other States Proposals | Spec PRs | Additional States
+-------+ | +------+ | +----------+ +-------+ | +------+ | +---------------+
| | | |
| | +----------------------+ | +---------+ | +-----------+
+----------+ | +---------+ | +---------+ | | | | | | | |
| | | | | | | | | Proposal | | +------> Spec PR | | | Postponed |
| Proposal | | +------> Spec PR | | | Blocked | | Drafting and Initial | | | | Missing | | | |
| WIP | | | | Missing | | | | | Feedback Gathering | | | | | | +-----------+
| | | | | | | +---------+ | | | | +----+----+ |
+----+-----+ | | +----+----+ | +----------+-----------+ | | | | +----------+
| | | | | | | | v | | |
| | | | | +-----------+ v | | +-----------------+ | | Closed |
+--------v----------+ | | | | | | +-------------------+ | | | | | | |
| | | | +---------v--------+ | | Abandoned | | | | | | Spec PR Created | | +----------+
| Proposal | | | | | | | | | Proposal PR | | | | and In Review | |
| Ready for Review | | | | Spec PR | | +-----------+ | Created | | | | | |
| | | | | Ready for Review | | | | | | +--------+--------+ |
+----------+--------+ | | | | | +-----------+ +---------+---------+ | | | |
| | | +---------+--------+ | | | | | | v |
| | | | | | Obsolete | v | | +-----------+ |
+------v----+ | | | | | | +-----------+ | | | | |
| | | | +-----v-----+ | +-----------+ | | | | | Spec PR | |
| Proposal | | | | | | | Proposal | | | | Merged! | |
| In Review | | | | Spec PR | | | In Review | | | | | |
| | | | | In Review | | +----------+ | | | | +-----------+ |
+----+------+ | | | | | | | +-----+-----+ | | |
| | | +-----+-----+ | | Rejected | | | | |
| | | | | | | v | | |
+------v--------+ | | | | +----------+ +----------------------+ | | |
| | | | | | | | | | |
| Proposal | | | +----v----+ | | Final Comment Period | | | |
| Passed Review | | | | | | | | | | |
| | | | | Merged! | | +----------+-----------+ | | |
+-------+-------+ | | | | | | | | |
| | | +---------+ | v | | |
| | | | +-------------+ | | |
+---------------+ | | | | | |
| | | Proposal PR | | | |
+ + | Merged! | | | |
| | | | |
+------+------+ | | |
| | | |
+-----------------+ |
| |
+ +
Lifetime States Lifetime States
--------------- ---------------
=========================== ======================================================= ============================= =======================================================
Proposal WIP A proposal document which is still work-in-progress but is being shared to incorporate feedback 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 now ready and waiting for review by the core team and community
Proposal In Review A proposal document which is currently in review Proposal Final Comment Period A proposal document which has reached final comment period either for merge, closure or postponement
Proposal Passed Review A proposal document which has passed review as worth implementing and then being added to the spec Proposal Merged A proposal document which has passed review
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 Spec PR Missing A proposal that has been accepted but has not currently been implemented in the spec
Spec PR Ready for Review A proposal which has been PR'd against the spec and is awaiting review Spec PR In Review A proposal that has been PR'd against the spec and is currently under review
Spec PR In Review A proposal which has been PR'd against the spec and is in review Spec PR Merged A proposal with a sufficient working implementation and whose Spec PR has been merged!
Merged A proposal whose PR has merged into the spec! Postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future
Blocked A proposal which is temporarily blocked on some external factor (e.g. being blocked on another proposal first being approved) Closed A proposal which has been reviewed and deemed unsuitable for acceptance
Abandoned A proposal where the author/shepherd has not been responsive for a few months ============================= =======================================================
Obsolete A proposal which has been overtaken by other proposals
Rejected A proposal which is not going to be incorporated into Matrix
=========================== =======================================================
Proposal Tracking Proposal Tracking
@ -189,24 +220,22 @@ This is a living document generated from the list of proposals at
`matrix-doc/issues <https://github.com/matrix-org/matrix-doc/issues>`_ on `matrix-doc/issues <https://github.com/matrix-org/matrix-doc/issues>`_ on
GitHub. GitHub.
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 issues based on those
on those which exist in the matrix-doc repo already. which exist in the matrix-doc repo already.
Other metadata: Other metadata:
- the MSC (Matrix Spec Change) number is taken from the github issue ID. This - the MSC (Matrix Spec Change) number is taken from the github Pull Request ID.
is carried for the lifetime of the proposal, including the PR creation This is carried for the lifetime of the proposal. These IDs do not necessary
phase. N.B. They are not in chronological order! represent a 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

Write Preview
Loading…
Cancel
Save