From 8c469e51cbf01caca3f2551e367dcd74de66d36d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 May 2018 22:05:28 +0100 Subject: [PATCH] lots of tweaks to the MSC verbiage --- specification/proposals_intro.rst | 47 +++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d6d79c92..f1a3adb6 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -3,13 +3,23 @@ Proposals for Spec Changes to Matrix ------------------------------------ + The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: -- produce a publicly-accessible Google Doc describing you change -- make a new issue at https://github.com/matrix-org/matrix-doc/issues with the metadata appropriate to the section below -- make a new PR which includes the proposed changed at https://github.com/matrix-org/matrix-doc/tree/master/specification +- produce a publicly-accessible proposal describing your change: + - Please use Google Docs, or an equivalent system capable of collaborative editing, with versioned history and threaded comments. + - 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 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. +- make a new issue at https://github.com/matrix-org/matrix-doc/issues, whose description should list the metadata as per below. +- Gather feedback as widely as possible from the community and core team on the proposal. + - The aim is to get maximum consensus on the trade-offs chosen to get an optimal solution. + - Iterating on the proposal and getting consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. +- Once the proposal has consensus and passed review, you **must** show an implementation to prove that it works well in practice, before before a spec PR will be accepted. Iterate on the proposal if needed. +- Finally, please make a new spec PR which includes the proposed changes against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! -The process for handling proposals is described in the following diagram. Note that there are corresponding labels for each stage available in the matrix-doc issue tracker. +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 `_. :: @@ -54,18 +64,37 @@ The process for handling proposals is described in the following diagram. Note t | | + + +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 is being used in the wild 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 is not responsive +Obsolete A proposal which has been overtaken by other proposals +Rejected A proposal which is not going to be incorporated into Matrix +=========================== ======================================================= + + 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 at `matrix-doc/issues `_ on GitHub. -We use labels and some metadata in the issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram above, these labels already exist in the matrix-doc repo. +We use labels and some metadata in the issue's description 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. +- 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. -- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. +- The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text. - Updated Date is taken from github. - Author is the creator of the github issue, but can be overriden by adding a "Author: @username" line in the body of the issue text. Please make sure @username is a github user (include the @!) -- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user. +- Shepherd is set by adding a "Shepherd: @username" line in the issue description. Again, make sure this is a real Github user.