From 42fd3f34e4daf8edcde68106f285e34ee0f9cb6f Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 May 2018 14:46:08 +0100 Subject: [PATCH] shift stuff from contributing.rst to the new proposals page --- CONTRIBUTING.rst | 43 +++++-------------------------- specification/proposals_intro.rst | 4 +-- 2 files changed, 9 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6f17afe6..2a7416b1 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,44 +21,15 @@ Matrix-doc workflows Specification changes ~~~~~~~~~~~~~~~~~~~~~ -The Matrix specification documents the APIs which Matrix clients can use. For -this to be effective, the APIs need to be present and working correctly in a -server before they can be documented in the specification. This process can -take some time to complete. +The Matrix specification documents the APIs which Matrix clients and servers use. +For this to be effective, the APIs need to be present and working correctly in a +server before they can be documented in the specification. This process can take +some time to complete. For this reason, we have not found the github pull-request model effective for -discussing changes to the specification. Instead, we have adopted the following -workflow: - -1. Create a discussion document outlining the proposed change. The document - should include details such as the HTTP endpoint being changed (or the - suggested URL for a new endpoint), any new or changed parameters and response - fields, and generally as much detail about edge-cases and error handling as - is practical at this stage. - - The Matrix Core Team's preferred tool for such discussion documents is - `Google Docs `_ thanks to its support for comment - threads. Works in progress are kept in the `Matrix Design drafts folder - `_. - -2. Seek feedback on the proposal. `#matrix-dev:matrix.org - `_ is a good place to reach the - core team and others who may be interested in your proposal. - -3. Implement the changes in servers and clients. Refer to the CONTRIBUTING files - of the relevant projects for details of how best to do this. - - In general we will be unable to publish specification updates until the - reference server implements them, and they have been proven by a working - client implementation. - -4. Iterate steps 1-3 as necessary. - -5. Write the specification for the change, and create a `pull request`_ for - it. It may be that much of the text of the change can be taken directly from - the discussion document, though typically some effort will be needed to - change to the ReST syntax and to ensure that the text is as clear as - possible. +discussing changes to the specification. Instead, we have adopted the workflow +as described at https://matrix.org/docs/spec/proposals - *please read this for +details on how to contribute spec changes*. Other changes diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index fd692e52..e1c467ca 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -21,9 +21,9 @@ The process for submitting a Matrix Spec Change (MSC) Proposal is as follows: - Iterating on the proposal and gathering consensus can sometimes be time-consuming; an impartial 'shepherd' can be assigned to help guide the proposal through this process. - 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! +- Finally, please make a new spec PR which includes the changes as implemented against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! Please sign off the spec PR as per the `CONTRIBUTING.rst `_ guidelines. -Final decisions on review are made by the +matrix:matrix.org community (i.e. the core team), acting on behalf of the whole Matrix community. +Final decisions on review are made by the Matrix core team (+matrix:matrix.org), acting on behalf of the whole Matrix community. 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.