diff --git a/scripts/proposals.py b/scripts/proposals.py index aa9ba5d31..0b0717d95 100644 --- a/scripts/proposals.py +++ b/scripts/proposals.py @@ -47,7 +47,7 @@ for label in labels: text_file = open("../specification/proposals.rst", "w") -text_file.write("Tables\n------------------\n\n") +text_file.write("Tables of Tracked Proposals\n---------------------------\n\n") for label in labels: diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index c87f5d1d4..d6d79c929 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -3,24 +3,13 @@ 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 -Proposal Tracking ------------------ - -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 below, these labels already exist in the matrix-doc repo. - -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. -- 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. -- 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. - +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. :: @@ -65,4 +54,18 @@ Other metadata: | | + + +Proposal Tracking +----------------- + +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. + +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. +- 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. +- 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.