diff --git a/proposals/0000-proposal-template.md b/proposals/0000-proposal-template.md
new file mode 100644
index 00000000..c32bde86
--- /dev/null
+++ b/proposals/0000-proposal-template.md
@@ -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.
diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst
index cc4d5d22..8784037e 100644
--- a/specification/proposals_intro.rst
+++ b/specification/proposals_intro.rst
@@ -6,97 +6,52 @@
Proposals for Spec Changes to Matrix
------------------------------------
-The process for submitting a Matrix Spec Change (MSC) Proposal is as follows:
-
-- Produce a publicly-accessible proposal describing your change:
-
- - Please use Google Docs, or an equivalent system capable of collaborative
- editing, with versioned history, suggestions ('track changes'), threaded
- comments, and good mobile support. Please ensure the document is
- world-commentable or -editable.
- - We do not use Github issues (or Etherpad) for the design process of the
- proposal, as the document review/commenting capabilities aren't good
- enough.
- - 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
- 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
- `_
- is available.
-
-- Make a new issue at https://github.com/matrix-org/matrix-doc/issues, whose
- 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 `_.
- 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
- `_
- guidelines.
-
-Final decisions on review are made by the Matrix core team
-(+matrix:matrix.org), acting on behalf of the whole Matrix community.
+If you are interested in submitting a change to the Matrix Specification,
+please take note of the following guidelines.
+
+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
+`_.
+
+Meet the `members of the Core Team
+`_, a group of
+individuals tasked with ensuring the spec process is as smooth and painless as
+possible. Members of the Core Team will do their best to participate in
+discussion, summarise when things become long-winded, and generally try to act
+towards the benefit of everyone. As a majority, team members have the ability
+to change the state of a proposal, and individually have the final say in
+proposal discussion.
+
+Guiding Principles
+------------------
Proposals **must** act to the greater benefit of the entire Matrix ecosystem,
-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
-to act as a neutral custodian for Matrix on behalf of the whole ecosystem,
-just as it has since Matrix's inception in May 2014.
+rather than benefiting or privileging any single player or subset of players -
+and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as
+a neutral custodian for Matrix on behalf of the whole ecosystem.
For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That
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
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.
"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
federated users)
-* the number of online servers in the open federation.
-* the number of developers building on Matrix.
+* the number of online servers in the open federation
+* the number of developers building on 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
-the upcoming governance proposal, but could be something like:
+In addition, proposal authors are expected to uphold the following values in
+their proposed changes to the Matrix protocol:
* Supporting the whole long-term ecosystem rather than individual stakeholder gain
* Openness rather than proprietariness
@@ -107,107 +62,208 @@ the upcoming governance proposal, but could be something like:
* Pragmatism rather than perfection
* Proof rather than conjecture
-The above directions are intended to be simple and pragmatic rather than
-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.
+Process
+-------
+
+The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as
+follows:
-The process for handling proposals is described in the following diagram. Note
-that the lifetime of a proposal is tracked through the corresponding labels for
-each stage in the `matrix-doc issue tracker
-`_.
+- Create a first draft of your proposal using `GitHub-flavored markdown
+ `_
+
+ - 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
+ `_
+ 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
+ `_ 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
+ `_ to give context
+ for the proposal.
+ - Additionally, please be sure to sign off your proposal PR as per the
+ guidelines listed on `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 `_.
+ 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
+ `_.
+
+- 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
+`_ issue and pull request trackers.
::
- + +
- Proposals | Spec PRs | Other States
- +-------+ | +------+ | +----------+
- | |
- | |
- +----------+ | +---------+ | +---------+
- | | | | | | | |
- | Proposal | | +------> Spec PR | | | Blocked |
- | WIP | | | | Missing | | | |
- | | | | | | | +---------+
- +----+-----+ | | +----+----+ |
- | | | | |
- | | | | | +-----------+
- +--------v----------+ | | | | | |
- | | | | +---------v--------+ | | Abandoned |
- | Proposal | | | | | | | |
- | Ready for Review | | | | Spec PR | | +-----------+
- | | | | | Ready for Review | |
- +----------+--------+ | | | | | +-----------+
- | | | +---------+--------+ | | |
- | | | | | | Obsolete |
- +------v----+ | | | | | |
- | | | | +-----v-----+ | +-----------+
- | Proposal | | | | | |
- | In Review | | | | Spec PR | |
- | | | | | In Review | | +----------+
- +----+------+ | | | | | | |
- | | | +-----+-----+ | | Rejected |
- | | | | | | |
- +------v--------+ | | | | +----------+
- | | | | | |
- | Proposal | | | +----v----+ |
- | Passed Review | | | | | |
- | | | | | Merged! | |
- +-------+-------+ | | | | |
- | | | +---------+ |
- | | | |
- +---------------+ |
- | |
- + +
+ + +
+ Proposals | Spec PRs | Additional States
+ +-------+ | +------+ | +---------------+
+ | |
+ +----------------------+ | +---------+ | +-----------+
+ | | | | | | | |
+ | Proposal | | +------= Spec PR | | | Postponed |
+ | Drafting and Initial | | | | Missing | | | |
+ | Feedback Gathering | | | | | | +-----------+
+ | | | | +----+----+ |
+ +----------+-----------+ | | | | +----------+
+ | | | v | | |
+ v | | +-----------------+ | | Closed |
+ +-------------------+ | | | | | | |
+ | | | | | Spec PR Created | | +----------+
+ | Proposal PR | | | | and In Review | |
+ | Created and | | | | | |
+ | In Review | | | +--------+--------+ |
+ | | | | | |
+ +---------+---------+ | | v |
+ | | | +-----------+ |
+ v | | | | |
+ +----------------------+ | | | Spec PR | |
+ | | | | | Merged! | |
+ | Final Comment Period | | | | | |
+ | | | | +-----------+ |
+ +----------+-----------+ | | |
+ | | | |
+ v | | |
+ +-------------+ | | |
+ | | | | |
+ | Proposal PR | | | |
+ | Merged! | | | |
+ | | | | |
+ +------|------+ | | |
+ | | | |
+ +-----------------+ |
+ | |
+ + +
Lifetime States
---------------
-=========================== =======================================================
-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
-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
-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 which has been PR'd against the spec and is in review
-Merged A proposal whose PR has merged into the spec!
-Blocked A proposal which is temporarily blocked on some external factor (e.g. being blocked on another proposal first being approved)
-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
-=========================== =======================================================
+**Note:** All labels are to be placed on the proposal PR.
+
+=============================== ============================= ====================================
+Name GitHub Label Description
+=============================== ============================= ====================================
+Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback
+Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Core Team and community
+Proposal Final Comment Period proposal-final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement
+Proposal Merged/Spec PR Missing spec-pr-missing A proposal document which has passed review. Waiting for a PR against the Spec
+Spec PR In Review spec-pr-in-review A proposal that has been PR'd against the spec and is currently under review
+Spec PR Merged merged A proposal with a sufficient working implementation and whose Spec PR has been merged!
+Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps
+ sometime in the future
+Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance
+=============================== ============================= ====================================
Proposal Tracking
-----------------
-This is a living document generated from the list of proposals at
-`matrix-doc/issues `_ on
-GitHub.
+This is a living document generated from the list of proposals on the issue and
+pull request trackers of the `matrix-doc
+`_ repo.
+
+We use labels and some metadata in MSC PR descriptions to generate this page.
+Labels are assigned by the Core Team whilst triaging the proposals based on those
+which exist in the `matrix-doc `_
+repo already.
-We use labels and some metadata in the issues' descriptions to generate this
-page. Labels are assigned by the core team whilst triaging the issues based
-on those which exist in the 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:
-- the MSC (Matrix Spec Change) number is taken from the github issue ID. This
- is carried for the lifetime of the proposal, including the PR creation
- phase. N.B. They are not in chronological order!
-- Please use the github issue title to set the title.
-- Please link to the proposal document by adding a "Documentation: " line
- in the issue description.
+- The MSC number is taken from the GitHub Pull Request ID. This is carried for
+ the lifetime of the proposal. These IDs do not necessary represent a
+ chronological order.
+- The GitHub PR title will act as the MSC's title.
- Please link to the spec PR (if any) by adding a "PRs: #1234" line in the
issue description.
-- The creation date is taken from the github issue, but can be overriden by
- adding a "Date: yyyy-mm-dd" line in the issue description.
-- Updated Date is taken from github.
-- Author is the creator of the github issue, but can be overriden by adding a
+- The creation date is taken from the GitHub PR, but can be overridden by
+ adding a "Date: yyyy-mm-dd" line in the PR description.
+- Updated Date is taken from GitHub.
+- 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
- 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
- issue description. Again, make sure this is a real Github user.
+ issue description. Again, make sure this is a real GitHub user.