Updates to README and CONTRIBUTING

CONTRIBUTING.rst

@@ -1,13 +1,22 @@
 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
 ~~~~~~~~~~~~~~~~~~~~~
@@ -29,8 +38,8 @@ workflow:
 
    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 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
    <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
 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
+  practice, servers and clients behave differently to the specification,
+  including anything with the `bug
+  <https://github.com/matrix-org/matrix-doc/labels/bug>`_ label.
+
+  (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. For example, recommendations for UI
+  problems for existing deployments. This includes anything with the
-  behaviour do not require a proposal document. On the other hand, changes to
+  `clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
-  event contents would be best discussed in a proposal document even though no
+  label.
-  changes would be necessary to server implementations.
+
+  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`_.
 
-
+.. _pull request: https://help.github.com/articles/about-pull-requests
-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
-~~~~~~~~~~
-
-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.
 
 Sign off
-~~~~~~~~
+--------
+
+We ask that everybody who contributes to their project signs off their
+contributions, as explained below.
+
+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

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 <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
 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 <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
 ==========================
 
@@ -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
+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: