From a3144e6959cefd62c5c30d30a81b6ce79d14a4a5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 02:33:15 +0200 Subject: [PATCH 01/38] Move to the new and improved MSC process --- specification/proposals_intro.rst | 255 +++++++++++++++++------------- 1 file changed, 142 insertions(+), 113 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index cc4d5d22..9d64c1dc 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -6,70 +6,98 @@ 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. +If you are interested in submitting a change to the matrix specification, +please take note of the following guidelines. + +Community changes to the specification require a formal proposal process. This +involves writing a proposal, having it reviewed by the matrix community, having +the proposal being accepted, then actually having your ideas implemented as +committed changes to the `specification repository +`_. + +The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as +follows: + +- 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. - - A `template with suggested headers + - However, a `template with suggested headers `_ - 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 + `_ 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 + `_ to give context + for your proposal. -- 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. +- Gather feedback as widely as possible from the community and core team. - - The aim is to get maximum consensus on the trade-offs chosen to get an - optimal solution. + - 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 `_. - 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. + However, it is welcome to use an alternative room if preferred please + advertise it in #matrix-spec:matrix.org and link to it on the PR for + visibility. + - 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. 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 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 - 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 - 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 +- Members of the core team 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. +- At some point a member of the core team will propose a motion for a final + comment period (FCP) with a *disposition* of merge, close or postpone. This + is usually preceded with a comment summarising the current state of the + 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 `_ guidelines. -Final decisions on review are made by the Matrix core team -(+matrix:matrix.org), acting on behalf of the whole Matrix community. +- 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 :) Proposals **must** act to the greater benefit of the entire Matrix ecosystem, 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 - +-------+ | +------+ | +----------+ - | | - | | - +----------+ | +---------+ | +---------+ - | | | | | | | | - | 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 | | | | | | + | | | | +--------+--------+ | + +---------+---------+ | | | | + | | | v | + v | | +-----------+ | + +-----------+ | | | | | + | | | | | Spec PR | | + | Proposal | | | | Merged! | | + | In Review | | | | | | + | | | | +-----------+ | + +-----+-----+ | | | + | | | | + v | | | + +----------------------+ | | | + | | | | | + | 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 -=========================== ======================================================= +============================= ======================================================= +Proposal WIP A proposal document which is still work-in-progress but is being shared to incorporate feedback +Proposal In Review A proposal document which is now ready and waiting for review by the core team and community +Proposal Final Comment Period A proposal document which has reached final comment period either for merge, closure or postponement +Proposal Merged A proposal document which has passed review +Spec PR Missing A proposal that has been accepted but has not currently been implemented in the spec +Spec PR In Review A proposal that has been PR'd against the spec and is currently under review +Spec PR Merged A proposal with a sufficient working implementation and whose Spec PR has been merged! +Postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future +Closed A proposal which has been reviewed and deemed unsuitable for acceptance +============================= ======================================================= Proposal Tracking @@ -189,24 +220,22 @@ This is a living document generated from the list of proposals at `matrix-doc/issues `_ on GitHub. -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. +We use labels and some metadata in MSC PR 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. 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 (Matrix Spec Change) 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. +- 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 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 sure @username is a github user (include the @!) - A shepherd can be assigned by adding a "Shepherd: @username" line in the From 764c63f3e84eb177daff2c8d3b2b5ec268f962b2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 15:22:23 +0200 Subject: [PATCH 02/38] Add proposal template --- proposals/proposal_template.md | 12 ++++++++++++ specification/proposals_intro.rst | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 proposals/proposal_template.md diff --git a/proposals/proposal_template.md b/proposals/proposal_template.md new file mode 100644 index 00000000..fb86d8fc --- /dev/null +++ b/proposals/proposal_template.md @@ -0,0 +1,12 @@ +# MSC Proposal Title + +## Problem/Background + +## Proposal/Solution + +## Tradeoffs + +## Potential Issues + +## Conclusion + diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 9d64c1dc..858db6f9 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -27,7 +27,7 @@ follows: 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 From d2e827e0c693cd74eff909c782da84a1f2321fca Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 15:46:26 +0200 Subject: [PATCH 03/38] Note about earlier MSC process --- specification/proposals_intro.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 858db6f9..08376b65 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -67,9 +67,9 @@ follows: the community. Having a shepherd is not a requirement for proposal acceptance. -- Members of the core team 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. +- 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. - At some point a member of the core team will propose a motion for a final comment period (FCP) with a *disposition* of merge, close or postpone. This is usually preceded with a comment summarising the current state of the @@ -224,9 +224,16 @@ We use labels and some metadata in MSC PR 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 Pull Request ID. +- The MSC (Matrix Spec Change) 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. From 80d1d4af9cd92d64bef19b612a6d78a4c9b2c1f0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 15:48:55 +0200 Subject: [PATCH 04/38] Fix capatilization --- specification/proposals_intro.rst | 64 +++++++++++++++---------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 08376b65..d661741c 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -6,19 +6,19 @@ Proposals for Spec Changes to Matrix ------------------------------------ -If you are interested in submitting a change to the matrix specification, +If you are interested in submitting a change to the Matrix Specification, please take note of the following guidelines. -Community changes to the specification require a formal proposal process. This -involves writing a proposal, having it reviewed by the matrix community, having +Community changes to the Specification require a formal proposal process. This +involves writing a proposal, having it reviewed by the Matrix community, having the proposal being accepted, then actually having your ideas implemented as -committed changes to the `specification repository -`_. +committed changes to the `Specification repository +`_. The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as follows: -- Create a first-draft of your proposal using `github-flavored markdown +- Create a first-draft of your proposal using `GitHub-flavored markdown `_ - In the document, clearly state the problem being solved, and the possible @@ -27,19 +27,19 @@ follows: 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. +- Fork and make a PR to the `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 - `_ to give context + - It is often very helpful to link any related MSCs or `Matrix-doc issues + `_ to give context for your proposal. - Gather feedback as widely as possible from the community and core team. @@ -48,14 +48,14 @@ follows: 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 `_. + `#Matrix-spec:Matrix.org `_. However, it is welcome to use an alternative room if preferred please - advertise it in #matrix-spec:matrix.org and link to it on the PR for + advertise it in #Matrix-spec:Matrix.org and link to it on the PR for visibility. - - 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 + - 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 @@ -68,7 +68,7 @@ follows: 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 + comments and in relevant rooms on Matrix. Discussion outside of GitHub should be summarised in a comment on the PR. - At some point a member of the core team will propose a motion for a final comment period (FCP) with a *disposition* of merge, close or postpone. This @@ -84,19 +84,19 @@ follows: 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 + 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 - `_ + `_ guidelines. - 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 + 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, @@ -145,8 +145,8 @@ possible. 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 -`_. +each stage in the `Matrix-doc issue tracker +`_. :: @@ -217,33 +217,33 @@ Proposal Tracking ----------------- This is a living document generated from the list of proposals at -`matrix-doc/issues `_ on +`Matrix-doc/issues `_ on GitHub. We use labels and some metadata in MSC PR 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. +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 +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 Pull Request ID. +- The MSC (Matrix Spec Change) 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. +- 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 PR, but can be overridden by +- 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. +- 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. From 9432ed76d77a27046c9e8f516a07e3c72aac54c3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 15:51:54 +0200 Subject: [PATCH 05/38] first-draft -> first draft --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d661741c..2a61269a 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -18,7 +18,7 @@ committed changes to the `Specification repository The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as follows: -- Create a first-draft of your proposal using `GitHub-flavored markdown +- Create a first draft of your proposal using `GitHub-flavored markdown `_ - In the document, clearly state the problem being solved, and the possible From 67146e4bec6a22b2915f411d25257924fbf727e2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 15:52:33 +0200 Subject: [PATCH 06/38] MSC ALL the changes --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 2a61269a..be8fd8c2 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -9,7 +9,7 @@ Proposals for Spec Changes to Matrix If you are interested in submitting a change to the Matrix Specification, please take note of the following guidelines. -Community changes to the Specification require a formal proposal process. This +All changes to Specification content require a formal proposal process. This involves writing a proposal, having it reviewed by the Matrix community, having the proposal being accepted, then actually having your ideas implemented as committed changes to the `Specification repository From f769084570da1b14088858e541972a529aed6301 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 15:54:28 +0200 Subject: [PATCH 07/38] Put it in the proposals dir! --- specification/proposals_intro.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index be8fd8c2..904afd5c 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -36,6 +36,9 @@ follows: - Fork and make a PR to the `Matrix-doc `_ repository. + - Your 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 From 0e9ad9e95d237abdded5a3d848653b808ecdec2e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:05:09 +0200 Subject: [PATCH 08/38] Fix wording, fix earlier capatilization --- specification/proposals_intro.rst | 39 ++++++++++++++++--------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 904afd5c..9ae71a2a 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -13,7 +13,7 @@ All changes to Specification content require a formal proposal process. This involves writing a proposal, having it reviewed by the Matrix community, having the proposal being accepted, then actually having your ideas implemented as committed changes to the `Specification repository -`_. +`_. The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as follows: @@ -27,22 +27,22 @@ follows: 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. +- Fork and make a PR to the `matrix-doc + `_ repository. - Your 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 + - It is often very helpful to link any related MSCs or `matrix-doc issues + `_ to give context for your proposal. - Gather feedback as widely as possible from the community and core team. @@ -51,14 +51,14 @@ follows: 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 `_. - However, it is welcome to use an alternative room if preferred please - advertise it in #Matrix-spec:Matrix.org and link to it on the PR for - visibility. - - For additional discussion areas, know that that #Matrix-dev:Matrix.org is - for developers using existing Matrix APIs, #Matrix:Matrix.org is for users + `#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 + #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 @@ -94,7 +94,7 @@ follows: during this process will warrant another MSC. - Please sign off the spec PR as per the `CONTRIBUTING.rst - `_ + `_ guidelines. - Your PR will then be reviewed and hopefully merged on the grounds it is @@ -148,8 +148,8 @@ possible. 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 -`_. +each stage in the `matrix-doc issue tracker +`_. :: @@ -220,18 +220,19 @@ Proposal Tracking ----------------- This is a living document generated from the list of proposals at -`Matrix-doc/issues `_ on +`matrix-doc/issues `_ on GitHub. We use labels and some metadata in MSC PR 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. +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 +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: From f1d71bd6c4011ebd5410a27df2b715abafb5fa8d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:09:04 +0200 Subject: [PATCH 09/38] Less complicated wording --- specification/proposals_intro.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 9ae71a2a..fe32cba5 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -83,9 +83,9 @@ follows: 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. + will be carried out. If sufficient reasoning against the disposition is 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 From 5ae3b50c6b414b869fef761ff37980037b17605e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:18:20 +0200 Subject: [PATCH 10/38] Require link to implementation --- specification/proposals_intro.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index fe32cba5..30ddb946 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -89,7 +89,8 @@ follows: - 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 + **must** show an implementation 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. From 11dbd5b56af6df8c4b4a179abd38425570268866 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:30:33 +0200 Subject: [PATCH 11/38] Proposal WIP -> drafting/feedback gathering --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 30ddb946..4dbcfdfa 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -205,7 +205,7 @@ Lifetime States --------------- ============================= ======================================================= -Proposal WIP A proposal document which is still work-in-progress but is being shared to incorporate feedback +Proposal Drafting/Feedback A proposal document which is still work-in-progress but is being shared to incorporate feedback Proposal In Review A proposal document which is now ready and waiting for review by the core team and community Proposal Final Comment Period A proposal document which has reached final comment period either for merge, closure or postponement Proposal Merged A proposal document which has passed review From 873641e4bc51f81c733f5abd51efd3abca8a304d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:34:41 +0200 Subject: [PATCH 12/38] Proposal Created and In Review is a single phase --- specification/proposals_intro.rst | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 4dbcfdfa..d639c67f 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -170,23 +170,16 @@ each stage in the `matrix-doc issue tracker +-------------------+ | | | | | | | | | | | | Spec PR Created | | +----------+ | Proposal PR | | | | and In Review | | - | Created | | | | | | - | | | | +--------+--------+ | - +---------+---------+ | | | | - | | | v | - v | | +-----------+ | - +-----------+ | | | | | - | | | | | Spec PR | | - | Proposal | | | | Merged! | | - | In Review | | | | | | - | | | | +-----------+ | - +-----+-----+ | | | - | | | | - v | | | - +----------------------+ | | | - | | | | | - | Final Comment Period | | | | - | | | | | + | Created and | | | | | | + | In Review | | | +--------+--------+ | + | | | | | | + +---------+---------+ | | v | + | | | +-----------+ | + v | | | | | + +----------------------+ | | | Spec PR | | + | | | | | Merged! | | + | Final Comment Period | | | | | | + | | | | +-----------+ | +----------+-----------+ | | | | | | | v | | | From b3f90f5825551c2a490f61d4805a436466e524e6 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:38:48 +0200 Subject: [PATCH 13/38] proposal passed = spec pr missing --- specification/proposals_intro.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d639c67f..beed4397 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -160,7 +160,7 @@ each stage in the `matrix-doc issue tracker | | +----------------------+ | +---------+ | +-----------+ | | | | | | | | - | Proposal | | +------> Spec PR | | | Postponed | + | Proposal | | +------= Spec PR | | | Postponed | | Drafting and Initial | | | | Missing | | | | | Feedback Gathering | | | | | | +-----------+ | | | | +----+----+ | @@ -188,7 +188,7 @@ each stage in the `matrix-doc issue tracker | Proposal PR | | | | | Merged! | | | | | | | | | - +------+------+ | | | + +------|------+ | | | | | | | +-----------------+ | | | @@ -197,17 +197,16 @@ each stage in the `matrix-doc issue tracker Lifetime States --------------- -============================= ======================================================= -Proposal Drafting/Feedback A proposal document which is still work-in-progress but is being shared to incorporate feedback -Proposal In Review A proposal document which is now ready and waiting for review by the core team and community -Proposal Final Comment Period A proposal document which has reached final comment period either for merge, closure or postponement -Proposal Merged A proposal document which has passed review -Spec PR Missing A proposal that has been accepted but has not currently been implemented in the spec -Spec PR In Review A proposal that has been PR'd against the spec and is currently under review -Spec PR Merged A proposal with a sufficient working implementation and whose Spec PR has been merged! -Postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future -Closed A proposal which has been reviewed and deemed unsuitable for acceptance -============================= ======================================================= +============================= ======================================================= +Proposal Drafting and Feedback A proposal document which is still work-in-progress but is being shared to incorporate feedback +Proposal In Review A proposal document which is now ready and waiting for review by the core team and community +Proposal Final Comment Period A proposal document which has reached final comment period either for merge, closure or postponement +Proposal Merged/Spec PR Missing A proposal document which has passed review. Waiting for a PR against the Spec +Spec PR In Review A proposal that has been PR'd against the spec and is currently under review +Spec PR Merged A proposal with a sufficient working implementation and whose Spec PR has been merged! +Postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future +Closed A proposal which has been reviewed and deemed unsuitable for acceptance +============================= ======================================================= Proposal Tracking From 604091380fcbb69d6182b4eece47e8969c568825 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 16:41:44 +0200 Subject: [PATCH 14/38] Attempt to fix contributing link --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index beed4397..2edee844 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -94,7 +94,7 @@ follows: 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 + - Please sign off the spec PR as per the `CONTRIBUTING.rst `_ guidelines. From fb4c50ec8aef4b0b4766c90701d2c79e602b3a26 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 23:37:41 +0200 Subject: [PATCH 15/38] No need to redefine MSC --- specification/proposals_intro.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 2edee844..6b2b84a4 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -69,6 +69,7 @@ follows: typically a neutral party from the core team or an experienced member of the community. 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 @@ -230,9 +231,9 @@ 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 Pull Request ID. - This is carried for the lifetime of the proposal. These IDs do not necessary - represent a chronological order. +- 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. From 49d017bdd5f85e6ab83263fcacdd71c562948e57 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 15 Oct 2018 23:51:28 +0200 Subject: [PATCH 16/38] your proposal -> the proposal --- specification/proposals_intro.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 6b2b84a4..fc0b75ca 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -36,14 +36,14 @@ follows: - Fork and make a PR to the `matrix-doc `_ repository. - - Your proposal must live in the ``proposals/`` directory with a filename + - 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 your proposal. + for the proposal. - Gather feedback as widely as possible from the community and core team. @@ -87,10 +87,10 @@ follows: will be carried out. If sufficient reasoning against the disposition is 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 +- 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 your spec PR to be accepted, you - **must** show an implementation to prove that it works well in practice. A + 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. From 889b46898c2a27e4a3d49f02b5b4605d71b40235 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 00:03:03 +0200 Subject: [PATCH 17/38] Move proposal etiquette to a separate document. --- specification/proposal_etiquette.rst | 42 +++++++++++++++++++++ specification/proposals_intro.rst | 56 ++++------------------------ specification/targets.yaml | 3 ++ 3 files changed, 52 insertions(+), 49 deletions(-) create mode 100644 specification/proposal_etiquette.rst diff --git a/specification/proposal_etiquette.rst b/specification/proposal_etiquette.rst new file mode 100644 index 00000000..f6339238 --- /dev/null +++ b/specification/proposal_etiquette.rst @@ -0,0 +1,42 @@ +.. title:: Proposal Etiquette + +Proposal Etiquette +------------------ + +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. + +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 +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 +the first place. + +"Greater benefit" could include maximising: + +* 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 independent implementations which use Matrix +* 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: + +* Supporting the whole long-term ecosystem rather than individual stakeholder gain +* Openness rather than proprietariness +* Collaboration rather than competition +* Accessibility rather than elitism +* Transparency rather than stealth +* Empathy rather than contrariness +* Pragmatism rather than perfection +* Proof rather than conjecture + +Return to the `proposals page `_. diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index fc0b75ca..5c8be40a 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -104,60 +104,18 @@ follows: 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, -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. - -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 -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 -the first place. - -"Greater benefit" could include maximising: - -* 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 independent implementations which use Matrix -* 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: - -* Supporting the whole long-term ecosystem rather than individual stakeholder gain -* Openness rather than proprietariness -* Collaboration rather than competition -* Accessibility rather than elitism -* Transparency rather than stealth -* Empathy rather than contrariness -* 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. - -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 +Please also read the separate document on `proposal etiquette `_. + +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 in the `matrix-doc issue tracker `_. :: + + - Proposals | Spec PRs | Additional States - +-------+ | +------+ | +---------------+ + Proposals | Spec PRs | Additional States + +-------+ | +------+ | +---------------+ | | +----------------------+ | +---------+ | +-----------+ | | | | | | | | diff --git a/specification/targets.yaml b/specification/targets.yaml index 93e1b8a6..179a8fe1 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -39,6 +39,9 @@ targets: files: - proposals_intro.rst - proposals.rst + proposal_etiquette: + files: + - proposal_etiquette.rst groups: # reusable blobs of files when prefixed with 'group:' modules: - modules/instant_messaging.rst From c1ecb9e324b87b44c6a010cd65c906210f23004c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 00:17:08 +0200 Subject: [PATCH 18/38] Fix up table with title and add corresponding GitHub labels --- specification/proposals_intro.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 5c8be40a..44b1eddd 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -156,16 +156,19 @@ labels for each stage in the `matrix-doc issue tracker Lifetime States --------------- -============================= ======================================================= -Proposal Drafting and Feedback A proposal document which is still work-in-progress but is being shared to incorporate feedback -Proposal In Review A proposal document which is now ready and waiting for review by the core team and community -Proposal Final Comment Period A proposal document which has reached final comment period either for merge, closure or postponement -Proposal Merged/Spec PR Missing A proposal document which has passed review. Waiting for a PR against the Spec -Spec PR In Review A proposal that has been PR'd against the spec and is currently under review -Spec PR Merged A proposal with a sufficient working implementation and whose Spec PR has been merged! -Postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future -Closed A proposal which has been reviewed and deemed unsuitable for acceptance -============================= ======================================================= +=============================== ============================= ==================================== +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 proposal-passed-review A proposal document which has passed review. Waiting for a PR against the Spec +Spec PR In Review spec-pr A proposal that has been PR'd against the spec and is currently under review +Spec PR Merged merged (on proposal pr) 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 From 8121bef771c97c83953148afd2e9ac431d9e2580 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 00:44:05 +0200 Subject: [PATCH 19/38] Introduce the spec core team --- specification/proposals_intro.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 44b1eddd..70b8510f 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -15,6 +15,15 @@ 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. + The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as follows: @@ -36,8 +45,8 @@ follows: - Fork and make a PR to the `matrix-doc `_ repository. - - 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 + - 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. @@ -45,7 +54,7 @@ follows: `_ to give context for the proposal. -- Gather feedback as widely as possible from the community and core team. +- Gather feedback as widely as possible from everyone. - 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 From 35c924308cba65d0ee6d7fcda54aea198d6e29a5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 00:57:08 +0200 Subject: [PATCH 20/38] core team -> Core Team --- specification/proposals_intro.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 70b8510f..3d20e5a4 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -15,10 +15,10 @@ the proposal being accepted, then actually having your ideas implemented as committed changes to the `Specification repository `_. -Meet the `members of the core team +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 +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 @@ -75,19 +75,19 @@ follows: 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 + typically a neutral party from the Core Team or an experienced member of the community. 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 +- 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. -- At some point a member of the core team will propose a motion for a final +- At some point a member of the Core Team will propose a motion for a final comment period (FCP) with a *disposition* of merge, close or postpone. This is usually preceded with a comment summarising the current state of the discussion, along with reasoning for the motion. -- A concern can be raised by a core team member at any time, which will block +- 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. @@ -169,7 +169,7 @@ Lifetime States 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 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 proposal-passed-review A proposal document which has passed review. Waiting for a PR against the Spec Spec PR In Review spec-pr A proposal that has been PR'd against the spec and is currently under review @@ -188,7 +188,7 @@ This is a living document generated from the list of proposals at GitHub. We use labels and some metadata in MSC PR descriptions to generate this page. -Labels are assigned by the core team whilst triaging the issues based on those +Labels are assigned by the Core Team whilst triaging the issues based on those which exist in the `matrix-doc `_ repo already. From 2f0025c7a779186e4d9745c9f8fecceb8150c727 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 00:57:11 +0200 Subject: [PATCH 21/38] Fix up wording in proposal etiquette --- specification/proposal_etiquette.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/specification/proposal_etiquette.rst b/specification/proposal_etiquette.rst index f6339238..ea64c2c2 100644 --- a/specification/proposal_etiquette.rst +++ b/specification/proposal_etiquette.rst @@ -4,17 +4,16 @@ Proposal Etiquette ------------------ 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 IP. 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 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: @@ -27,8 +26,8 @@ the first place. * the number of independent implementations which use Matrix * 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 From 7753957d0446a092fa086d12715317cfcc6aaa11 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 01:04:54 +0200 Subject: [PATCH 22/38] remove ambiguity --- specification/proposals_intro.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 3d20e5a4..5b70c1a4 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -9,9 +9,9 @@ Proposals for Spec Changes to Matrix 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 the Matrix community, having -the proposal being accepted, then actually having your ideas implemented as +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 `_. From aeea060bb8c832023305810df3df5b421e5769e9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 01:06:44 +0200 Subject: [PATCH 23/38] Specify where to find the MSC ID --- specification/proposals_intro.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 5b70c1a4..17234d02 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -43,7 +43,8 @@ follows: be poorly received by the community. - Fork and make a PR to the `matrix-doc - `_ repository. + `_ 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 From 5a1e735921e2363cc61d1f838cbef44d0dce3c70 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 01:21:14 +0200 Subject: [PATCH 24/38] Fix sign off bullet --- specification/proposals_intro.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 17234d02..c7c6f9f9 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -80,7 +80,6 @@ follows: the community. 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. @@ -105,9 +104,9 @@ follows: 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 - `_ - guidelines. + - Please sign off the spec PR as per the `CONTRIBUTING.rst + `_ + guidelines. - 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 From c430ca32afb9fb004b830f03ce0f43181dc15652 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Oct 2018 15:14:43 +0200 Subject: [PATCH 25/38] New proposal template about proposal templates about... --- proposals/proposal_template.md | 109 +++++++++++++++++++++++++++++++-- 1 file changed, 105 insertions(+), 4 deletions(-) diff --git a/proposals/proposal_template.md b/proposals/proposal_template.md index fb86d8fc..c32bde86 100644 --- a/proposals/proposal_template.md +++ b/proposals/proposal_template.md @@ -1,12 +1,113 @@ -# MSC Proposal Title +# Example: Proposal to adopt a template for MSCs -## Problem/Background +*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. -## Proposal/Solution ## Tradeoffs -## Potential Issues +*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. From 148f7d7b339084d12f7833cfa7abb9927976756b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 17 Oct 2018 14:34:57 +0200 Subject: [PATCH 26/38] Minor proposal updates are allowed --- specification/proposals_intro.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index c7c6f9f9..e8170d0f 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -102,7 +102,10 @@ follows: 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. + 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. - Please sign off the spec PR as per the `CONTRIBUTING.rst `_ From 748a81523cf392668488d8f532fbb3b4c4d3aec4 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 17 Oct 2018 14:47:40 +0200 Subject: [PATCH 27/38] Rename proposal template to MSC #0000 --- proposals/{proposal_template.md => 0000-proposal-template.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{proposal_template.md => 0000-proposal-template.md} (100%) diff --git a/proposals/proposal_template.md b/proposals/0000-proposal-template.md similarity index 100% rename from proposals/proposal_template.md rename to proposals/0000-proposal-template.md From 1e939c50f5354304f60e3b3221b97a9e0f5c1bcf Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 17 Oct 2018 14:49:01 +0200 Subject: [PATCH 28/38] Gather feedback --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index e8170d0f..48291e25 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -55,7 +55,7 @@ follows: `_ to give context for the proposal. -- Gather feedback as widely as possible from everyone. +- 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 From 45c935d8d34ee28e079c1ac97fab34319c08e644 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 17 Oct 2018 15:35:15 +0200 Subject: [PATCH 29/38] Clarify that MSCs aren't just issues anymore. --- specification/proposals_intro.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 48291e25..5fb73498 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -36,7 +36,7 @@ follows: 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 @@ -120,8 +120,8 @@ Please also read the separate document on `proposal etiquette `_. +labels for each stage on the `matrix-doc +`_ issue and pull request trackers. :: @@ -186,12 +186,12 @@ Closed proposal-closed A proposal which 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 issues based on those +Labels are assigned by the Core Team whilst triaging the proposals based on those which exist in the `matrix-doc `_ repo already. From d487c0974f704676ce36bc71133b77c167bc430e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 17 Oct 2018 17:17:07 +0200 Subject: [PATCH 30/38] Clarify how to get a shepherd (just ask) --- specification/proposals_intro.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 5fb73498..30ed2fff 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -77,7 +77,9 @@ follows: 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. Having a shepherd is not a requirement for proposal + 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 From 9625f11fd4f193483302bd3316b8257548d0f654 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 17 Oct 2018 18:20:42 +0200 Subject: [PATCH 31/38] reduce abbreviations --- specification/proposal_etiquette.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposal_etiquette.rst b/specification/proposal_etiquette.rst index ea64c2c2..59df3122 100644 --- a/specification/proposal_etiquette.rst +++ b/specification/proposal_etiquette.rst @@ -5,7 +5,7 @@ Proposal Etiquette 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. Members of the Core Team pledge to act as +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 From 5a2d28e7fdf7a802a0b462549044eaca587f0804 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 17 Oct 2018 18:21:16 +0200 Subject: [PATCH 32/38] Reduce more abbreviations! --- specification/proposal_etiquette.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposal_etiquette.rst b/specification/proposal_etiquette.rst index 59df3122..585e85c0 100644 --- a/specification/proposal_etiquette.rst +++ b/specification/proposal_etiquette.rst @@ -10,7 +10,7 @@ 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 those who created it in From 7bff4d288c3e84b0c9271e8f76f99e504e918e63 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 18 Oct 2018 15:52:28 +0200 Subject: [PATCH 33/38] be begin -> begin --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 30ed2fff..53f63de4 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -90,7 +90,7 @@ follows: is usually preceded with a comment summarising the current state of the 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 + the 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 From f00be6b0d83729cdc0d0b4c3a9523b5d60dede8f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sat, 20 Oct 2018 23:35:33 +0200 Subject: [PATCH 34/38] Etiquette -> guiding principles --- specification/proposal_etiquette.rst | 41 -------------------------- specification/proposals_intro.rst | 43 ++++++++++++++++++++++++++-- 2 files changed, 41 insertions(+), 43 deletions(-) delete mode 100644 specification/proposal_etiquette.rst diff --git a/specification/proposal_etiquette.rst b/specification/proposal_etiquette.rst deleted file mode 100644 index 585e85c0..00000000 --- a/specification/proposal_etiquette.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. title:: Proposal Etiquette - -Proposal Etiquette ------------------- - -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 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 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 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 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 independent implementations which use Matrix -* the quality and utility of the Matrix spec - -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 -* Collaboration rather than competition -* Accessibility rather than elitism -* Transparency rather than stealth -* Empathy rather than contrariness -* Pragmatism rather than perfection -* Proof rather than conjecture - -Return to the `proposals page `_. diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 53f63de4..1507bd56 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -24,6 +24,47 @@ 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 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 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 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 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 independent implementations which use Matrix +* the quality and utility of the Matrix spec + +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 +* Collaboration rather than competition +* Accessibility rather than elitism +* Transparency rather than stealth +* Empathy rather than contrariness +* Pragmatism rather than perfection +* Proof rather than conjecture + +Process +------- + The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as follows: @@ -118,8 +159,6 @@ follows: you've contributed to the Matrix protocol for the benefit of users and developers alike :) -Please also read the separate document on `proposal etiquette `_. - 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 From 0afb1227603e7b1c9bc7521ac550e2b86a5a4194 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sat, 20 Oct 2018 23:50:26 +0200 Subject: [PATCH 35/38] Clarification on FCPs --- specification/proposals_intro.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 1507bd56..72fb95ab 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -126,17 +126,20 @@ follows: - 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. -- At some point a member of the Core Team will propose a motion for a final - comment period (FCP) with a *disposition* of merge, close or postpone. This - is usually preceded with a comment summarising the current state of the - discussion, along with reasoning for the motion. +- 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 - the FCP from beginning. An FCP will only begin when a **majority** of core + 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 is + 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 From 4b858a799342549dd0763f531f553abc862b4a33 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 21 Oct 2018 00:52:39 +0200 Subject: [PATCH 36/38] DCO required for proposal and spec PR --- specification/proposals_intro.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 72fb95ab..45bcd8b8 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -95,6 +95,9 @@ follows: - 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 at `CONTRIBUTING.rst + `_. - Gather feedback as widely as possible. @@ -153,9 +156,9 @@ follows: document. This ensures that someone reading a proposal in the future doesn't assume old information wasn't merged into the spec. - - Please sign off the spec PR as per the `CONTRIBUTING.rst - `_ - guidelines. + - Similar to the proposal PR, please sign off the spec PR as per the + guidelines at `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 From 2b259c6a7bb897c3c95c124ee6d758fc78e2a08f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 21 Oct 2018 00:54:04 +0200 Subject: [PATCH 37/38] Remove etiquette page from targets --- specification/targets.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/specification/targets.yaml b/specification/targets.yaml index 179a8fe1..93e1b8a6 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -39,9 +39,6 @@ targets: files: - proposals_intro.rst - proposals.rst - proposal_etiquette: - files: - - proposal_etiquette.rst groups: # reusable blobs of files when prefixed with 'group:' modules: - modules/instant_messaging.rst From f8ffa79b56cc726b057ea404599d8f9a8ba10795 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 23 Oct 2018 19:37:51 +0200 Subject: [PATCH 38/38] Update and clarify proposal labels --- specification/proposals_intro.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 45bcd8b8..8784037e 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -96,7 +96,7 @@ follows: `_ to give context for the proposal. - Additionally, please be sure to sign off your proposal PR as per the - guidelines at `CONTRIBUTING.rst + guidelines listed on `CONTRIBUTING.rst `_. - Gather feedback as widely as possible. @@ -157,7 +157,7 @@ follows: assume old information wasn't merged into the spec. - Similar to the proposal PR, please sign off the spec PR as per the - guidelines at `CONTRIBUTING.rst + guidelines on `CONTRIBUTING.rst `_. - Your PR will then be reviewed and hopefully merged on the grounds it is @@ -215,15 +215,17 @@ labels for each stage on the `matrix-doc Lifetime States --------------- +**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 proposal-passed-review A proposal document which has passed review. Waiting for a PR against the Spec -Spec PR In Review spec-pr A proposal that has been PR'd against the spec and is currently under review -Spec PR Merged merged (on proposal pr) A proposal with a sufficient working implementation and whose Spec PR has been merged! +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