add special-snowflake CONTRIBUTING for matrix-doc
Richard van der Hoff
8 years ago
parent
ac006f8e1e
commit
85594d4d97
@ -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 <https://docs.google.com>`_ thanks to its support for comment
|
||||||
|
threads.
|
||||||
|
|
||||||
|
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. 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 <your@email.example.org>
|
||||||
|
|
||||||
|
...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 :)
|
||||||
|
|||||||
Loading…
Reference in New Issue