wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

shift stuff from contributing.rst to the new proposals page

Browse source
This commit is contained in:
Matthew Hodgson 2018-05-15 14:46:08 +01:00
parent 3b736388ce
commit 42fd3f34e4
2 changed files with 9 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

43
CONTRIBUTING.rst
View file

@ -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 <https://docs.google.com>`_ thanks to its support for comment
threads. Works in progress are kept in the `Matrix Design drafts folder
<https://drive.google.com/drive/folders/0B4wHq8qP86r2ck15MHEwMmlNVUk>`_.
2. Seek feedback on the proposal. `#matrix-dev:matrix.org
<http://matrix.to/#/#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

4
specification/proposals_intro.rst
View file

@ -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 <https://github.com/matrix-org/matrix-doc/blob/master/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.