From d9285cf5b509c162ac1075495758b0555812b1d2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 8 Nov 2017 08:12:14 +0000 Subject: [PATCH] Updates to README and CONTRIBUTING --- CONTRIBUTING.rst | 84 +++++++++++++++++++++++++++--------------------- README.rst | 41 ++++++++++++++++------- 2 files changed, 78 insertions(+), 47 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index f18263d0..e0aa8318 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,13 +1,22 @@ Contributing to matrix-doc ========================== -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). +Everyone is welcome to contribute to the Matrix specification! + +Please ensure that you sign off your contributions. See `Sign off`_ below. + +Code style +---------- + +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 ~~~~~~~~~~~~~~~~~~~~~ @@ -29,8 +38,8 @@ workflow: 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 a folder at - https://drive.google.com/drive/folders/0B4wHq8qP86r2ck15MHEwMmlNVUk. + 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 @@ -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 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 + `_ label). -* 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. 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. +* Likewise, corrections to the specification, to fix situations where, in + practice, servers and clients behave differently to the specification, + including anything with the `bug + `_ label. -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 + `_.) +* 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 `_ + label. -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/). + 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. -(Note that, unlike most of the other matrix.org projects, pull requests for -matrix-doc should be based on the ``master`` branch.) +For such changes, please do just open a `pull request`_. -Code style -~~~~~~~~~~ +.. _pull request: https://help.github.com/articles/about-pull-requests -The documentation style is described at -https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst. +Sign off +-------- -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. +We ask that everybody who contributes to their project signs off their +contributions, as explained below. -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 and you agree to license it under the same terms as the project's license, we've adopted the diff --git a/README.rst b/README.rst index 8a0e1d0e..82772483 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,11 @@ This repository contains the Matrix specification. +If you want to ask more about the specification, join us on +`#matrix-dev:matrix.org `_. + +We welcome contributions to the spec! See the notes below on `Building the +specification`_, and ``_ to get started making contributions. + Note that the Matrix Project lists, which were previously kept in this 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 .. _JSON Schema: http://json-schema.org/ -Contributing -============ - -If you want to ask more about the specification, join us on -`#matrix-dev:matrix.org `_. - -If you would like to contribute to the specification or supporting -documentation, see ``_. - Building the specification ========================== @@ -98,11 +95,33 @@ To make use of the generated file, there are a number of options: .. _`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 ============== -Issues with the Matrix specification and supporting documentation are tracked -in `GitHub `_. +Issues with the Matrix specification are tracked in `GitHub +`_. The following labels are used to help categorize issues: