From 85594d4d971a43dc466c0a897dbc834e37233f70 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 13 Jul 2016 10:51:03 +0100 Subject: [PATCH 1/3] add special-snowflake CONTRIBUTING for matrix-doc --- CONTRIBUTING.rst | 141 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index fce62619..2faf8b01 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,4 +1,139 @@ -Contributing code to matrix-doc -=============================== +Contributing to matrix-doc +========================== -matrix-doc follows the same pattern as https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst +Everyone is welcome to contribute to the ``matrix-doc`` project, provided that they +are willing to license their contributions under the same license as the +project itself. We follow a simple 'inbound=outbound' model for contributions: +the act of submitting an 'inbound' contribution means that the contributor +agrees to license the code under the same terms as the project's overall +'outbound' license - in our case, this is Apache Software License +v2 (see LICENSE). + +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. + +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 Sheets `_ thanks to its support for comment + threads. + +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. Prototype the changes in servers and clients. Refer to the CONTRIBUTING files + of the relevant projects for details of how best to do this. + +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. + + +Other changes +~~~~~~~~~~~~~ + +The above process is unnecessary for smaller changes, and those which do not +put new requirements on servers. This category of changes includes the +following: + +* changes to supporting documentation +* changes to the scripts used to generate the specification +* clarifications to the specification which do not change the behaviour of + Matrix servers. + +For such changes, please do just open a `pull request`_. + + +Pull requests +~~~~~~~~~~~~~ +.. _pull request: `Pull requests`_ + +The preferred and easiest way to contribute changes to the ``matrix-doc`` project +is to fork it on github, and then create a pull request to ask us to pull your +changes into our repo (https://help.github.com/articles/using-pull-requests/). + +(Note that, unlike most of the other matrix.org projects, pull requests for +matrix-doc should be based on the ``master`` branch.) + +Code style +~~~~~~~~~~ + +Python code within the ``matrix-doc`` project should follow the same style as +synapse, which is documented at +https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst. + +Sign off +~~~~~~~~ + +In order to have a concrete record that your contribution is intentional +and you agree to license it under the same terms as the project's license, we've adopted the +same lightweight approach that the Linux Kernel +(https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker +(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other +projects use: the DCO (Developer Certificate of Origin: +http://developercertificate.org/). This is a simple declaration that you wrote +the contribution or otherwise have the right to contribute it to Matrix:: + + Developer Certificate of Origin + Version 1.1 + + Copyright (C) 2004, 2006 The Linux Foundation and its contributors. + 660 York Street, Suite 102, + San Francisco, CA 94110 USA + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +If you agree to this for your contribution, then all that's needed is to +include the line in your commit or pull request comment:: + + Signed-off-by: Your Name + +...using your real name; unfortunately pseudonyms and anonymous contributions +can't be accepted. Git makes this trivial - just use the -s flag when you do +``git commit``, having first set ``user.name`` and ``user.email`` git configs +(which you should have done anyway :) From 6cfc025bb851176bbf80283afffb7fbfa65c460c Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 13 Jul 2016 11:32:40 +0100 Subject: [PATCH 2/3] CONTRIBUTING: add link to docs folder --- CONTRIBUTING.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2faf8b01..e775c218 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -28,8 +28,9 @@ workflow: is practical at this stage. The Matrix Core Team's preferred tool for such discussion documents is - `Google Sheets `_ thanks to its support for comment - threads. + `Google Docs `_ thanks to its support for comment + threads. Works in progress are kept in a folder at + https://drive.google.com/drive/folders/0B4wHq8qP86r2ck15MHEwMmlNVUk. 2. Seek feedback on the proposal. `#matrix-dev:matrix.org `_ is a good place to reach the From 9eba63b816f2d91e355bff171eb251b7a650582e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 13 Jul 2016 12:19:42 +0100 Subject: [PATCH 3/3] CONTRIBUTING PR feedback * Make it clear that we won't do spec changes unless backed up by working implementations. * Try to pin down when we expect a proposal doc a bit better --- CONTRIBUTING.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index e775c218..1cbba00b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -36,9 +36,13 @@ workflow: `_ is a good place to reach the core team and others who may be interested in your proposal. -3. Prototype the changes in servers and clients. Refer to the CONTRIBUTING files +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 @@ -56,9 +60,15 @@ put new requirements on servers. This category of changes includes the following: * changes to supporting documentation + * changes to the scripts used to generate the specification + * clarifications to the specification which do not change the behaviour of - Matrix servers. + Matrix servers or clients in a way which might introduce compatibility + problems for existing deployments. For example, recommendations for UI + behaviour do not require a proposal document. On the other hand, changes to + event contents would be best discussed in a proposal document even though no + changes would be necessary to server implementations. For such changes, please do just open a `pull request`_.