Updates to README and CONTRIBUTING

pull/977/head
Richard van der Hoff 7 years ago
parent de6b0a278e
commit d9285cf5b5

@ -1,13 +1,22 @@
Contributing to matrix-doc Contributing to matrix-doc
========================== ==========================
Everyone is welcome to contribute to the ``matrix-doc`` project, provided that they Everyone is welcome to contribute to the Matrix specification!
are willing to license their contributions under the same license as the
project itself. We follow a simple 'inbound=outbound' model for contributions: Please ensure that you sign off your contributions. See `Sign off`_ below.
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 Code style
'outbound' license - in our case, this is Apache Software License ----------
v2 (see LICENSE).
The documentation style is described at
https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
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.
Matrix-doc workflows
--------------------
Specification changes Specification changes
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@ -29,8 +38,8 @@ workflow:
The Matrix Core Team's preferred tool for such discussion documents is The Matrix Core Team's preferred tool for such discussion documents is
`Google Docs <https://docs.google.com>`_ thanks to its support for comment `Google Docs <https://docs.google.com>`_ thanks to its support for comment
threads. Works in progress are kept in a folder at threads. Works in progress are kept in the `Matrix Design drafts folder
https://drive.google.com/drive/folders/0B4wHq8qP86r2ck15MHEwMmlNVUk. <https://drive.google.com/drive/folders/0B4wHq8qP86r2ck15MHEwMmlNVUk>`_.
2. Seek feedback on the proposal. `#matrix-dev:matrix.org 2. Seek feedback on the proposal. `#matrix-dev:matrix.org
<http://matrix.to/#/#matrix-dev:matrix.org>`_ is a good place to reach the <http://matrix.to/#/#matrix-dev:matrix.org>`_ is a good place to reach the
@ -59,43 +68,46 @@ The above process is unnecessary for smaller changes, and those which do not
put new requirements on servers. This category of changes includes the put new requirements on servers. This category of changes includes the
following: following:
* changes to supporting documentation * Changes to the scripts used to generate the specification.
* changes to the scripts used to generate the specification * Addition of features which have been in use in practice for some time, but
have never made it into the spec (including anything with the `spec-omission
<https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_ label).
* clarifications to the specification which do not change the behaviour of * Likewise, corrections to the specification, to fix situations where, in
Matrix servers or clients in a way which might introduce compatibility practice, servers and clients behave differently to the specification,
problems for existing deployments. For example, recommendations for UI including anything with the `bug
behaviour do not require a proposal document. On the other hand, changes to <https://github.com/matrix-org/matrix-doc/labels/bug>`_ label.
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`_. (If there is any doubt about whether it is the spec or the implementations
that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
<http://matrix.to/#/#matrix-dev:matrix.org>`_.)
* Clarifications to the specification which do not change the behaviour of
Matrix servers or clients in a way which might introduce compatibility
problems for existing deployments. This includes anything with the
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
label.
Pull requests For example, recommendations for UI behaviour do not require a proposal
~~~~~~~~~~~~~ document. On the other hand, changes to event contents would be best
.. _pull request: `Pull requests`_ discussed in a proposal document even though no changes would be necessary to
server implementations.
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 For such changes, please do just open a `pull request`_.
matrix-doc should be based on the ``master`` branch.)
Code style .. _pull request: https://help.github.com/articles/about-pull-requests
~~~~~~~~~~
The documentation style is described at Sign off
https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst. --------
Python code within the ``matrix-doc`` project should follow the same style as We ask that everybody who contributes to their project signs off their
synapse, which is documented at contributions, as explained below.
https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst.
Sign off We follow a simple 'inbound=outbound' model for contributions: the act of
~~~~~~~~ submitting an 'inbound' contribution means that the contributor agrees to
license their contribution under the same terms as the project's overall 'outbound'
license - in our case, this is Apache Software License v2 (see LICENSE).
In order to have a concrete record that your contribution is intentional 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 and you agree to license it under the same terms as the project's license, we've adopted the

@ -1,5 +1,11 @@
This repository contains the Matrix specification. This repository contains the Matrix specification.
If you want to ask more about the specification, join us on
`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
We welcome contributions to the spec! See the notes below on `Building the
specification`_, and `<CONTRIBUTING.rst>`_ to get started making contributions.
Note that the Matrix Project lists, which were previously kept in this Note that the Matrix Project lists, which were previously kept in this
repository, are now in https://github.com/matrix-org/matrix.org. repository, are now in https://github.com/matrix-org/matrix.org.
@ -28,15 +34,6 @@ Structure of this repository
.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md .. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
.. _JSON Schema: http://json-schema.org/ .. _JSON Schema: http://json-schema.org/
Contributing
============
If you want to ask more about the specification, join us on
`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
If you would like to contribute to the specification or supporting
documentation, see `<CONTRIBUTING.rst>`_.
Building the specification Building the specification
========================== ==========================
@ -98,11 +95,33 @@ To make use of the generated file, there are a number of options:
.. _`Swagger`: http://swagger.io/ .. _`Swagger`: http://swagger.io/
Continuserv
-----------
Continuserv is a script which will rebuild the specification every time a file
is changed, and will serve it to a browser over HTTP. It is intended for use by
specification authors, so that they can quickly see the effects of their
changes.
It is written in Go, so you will need the ``go`` compiler installed on your
computer. You will also need to install fsnotify by running::
go get gopkg.in/fsnotify.v1
Then, create a virtualenv as described above under `Preparation`_,
and::
source env/bin/activate
go run ./scripts/continuserv/main.go
You will then be able to view the generated spec by visiting
http://localhost:8000/index.html.
Issue tracking Issue tracking
============== ==============
Issues with the Matrix specification and supporting documentation are tracked Issues with the Matrix specification are tracked in `GitHub
in `GitHub <https://github.com/matrix-org/matrix-doc/issues>`_. <https://github.com/matrix-org/matrix-doc/issues>`_.
The following labels are used to help categorize issues: The following labels are used to help categorize issues:

Loading…
Cancel
Save