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: