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.