Merge branch 'master' into travis/msc/integrations/openid

Author: turt2live

.buildkite/pipeline.yaml

@@ -0,0 +1,16 @@
+steps:
+  - label: ":books: Build spec"
+    command:
+      - python3 -m venv env
+      - env/bin/pip install -r scripts/requirements.txt
+      - ". env/bin/activate; scripts/generate-matrix-org-assets"
+    artifact_paths:
+      - assets.tar.gz
+    plugins:
+      - docker#v3.0.1:
+          image: "python:3.6"
+
+  - label: "rebuild matrix.org"
+    trigger: "matrix-dot-org"
+    async: true
+    branches: "master"

.circleci/config.yml

@@ -97,7 +97,7 @@ jobs:
           command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL
   build-dev-scripts:
     docker:
-      - image: golang:1.8
+      - image: golang:1.10
     steps:
       - checkout
       - run:
@@ -121,4 +121,4 @@ workflows:
 
 notify:
   webhooks:
-    - url: https://giles.cadair.com/circleci
+    - url: https://giles.cadair.dev/circleci

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+patreon: matrixdotorg
+liberapay: matrixdotorg

.github/PULL_REQUEST_TEMPLATE/ready-proposal.md

@@ -0,0 +1,19 @@
+---
+name: Proposal ready for review
+about: A proposal that is ready for review by the core team and community.
+title: ''
+labels: proposal, proposal-in-review
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Pull request title and file name include this PR's number as the MSC number.

.github/PULL_REQUEST_TEMPLATE/spec-change.md

@@ -0,0 +1,16 @@
+---
+name: Spec clarification/not a proposal
+about: A change that's not a spec proposal, such as a clarification to the spec itself.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes)

.github/PULL_REQUEST_TEMPLATE/wip-proposal.md

@@ -0,0 +1,20 @@
+---
+name: WIP Proposal
+about: A proposal that isn't quite ready for formal review yet.
+title: '[WIP] Your Proposal Title'
+labels: proposal
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
+* [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review.

.gitignore

@@ -12,3 +12,4 @@
 *.swp
 _rendered.rst
 /.vscode/
+/.idea/

CONTRIBUTING.rst

@@ -13,7 +13,7 @@ https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rs
 
 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.
+https://github.com/matrix-org/synapse/tree/master/docs/code_style.md.
 
 Matrix-doc workflows
 --------------------
@@ -26,10 +26,11 @@ 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 workflow
-as described at https://matrix.org/docs/spec/proposals - *please read this for
-details on how to contribute spec changes*.
+Changes to the protocol (new endpoints, ideas, etc) need to go through the
+`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
+such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
+If you're not sure, visit us at `#matrix-spec:matrix.org`_
+and ask.
 
 
 Other changes
@@ -51,32 +52,31 @@ following:
   <https://github.com/matrix-org/matrix-doc/labels/spec-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>`_.)
+  that need fixing, please discuss it with us first in `#matrix-spec: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.
 
-  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 example, areas where the specification is unclear do not require a proposal
+  to fix. On the other hand, introducing new behaviour is best represented by a
+  proposal.
 
-For such changes, please do just open a `pull request`_.
+For such changes, please do just open a `pull request`_. If you're not sure if
+your change is covered by the above, please visit `#matrix-spec:matrix.org` and
+ask.
 
-.. _pull request: https://help.github.com/articles/about-pull-requests
+.. _`pull request`: https://help.github.com/articles/about-pull-requests
+.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
 
 
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Currently only changes to the client-server API need to end up in a changelog. The
-other APIs are not yet stable and therefore do not have a changelog. Adding to the
-changelog can only be done after you've opened your pull request, so be sure to do
-that first.
+All API specifications require a changelog entry. Adding to the changelog can only
+be done after you've opened your pull request, so be sure to do that first.
 
 The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
 form of "news fragments". The news fragments for the client-server API are stored
@@ -96,7 +96,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``breaking`` - Used when the change is not backwards compatible.
 
-* ``deprecation`` - Used when deprecating something
+* ``deprecation`` - Used when deprecating something.
 
 All news fragments must have a brief summary explaining the change in the
 contents of the file. The summary must end in a full stop to be in line with

README.rst

@@ -46,7 +46,7 @@ To use the scripts, it is best to create a Python 3.4+ virtualenv as follows::
   virtualenv -p python3 env
   env/bin/pip install -r scripts/requirements.txt
 
-(Benjamin Synders has contributed a script for `Nix`_ users, which can be
+(Benjamin Saunders has contributed a script for `Nix`_ users, which can be
 invoked with ``nix-shell scripts/contrib/shell.nix``.)
 
 .. TODO: Possibly we need some libs installed; should record what they are.
@@ -66,12 +66,14 @@ The above will write the rendered version of the specification to
 
 Windows users
 ~~~~~~~~~~~~~
+The ``source`` program does not exist on Windows, so instead run one of the 
+``activate`` files in ``.\env\Scripts\`` to activate the virtual environment.
 
 If you're on Windows Vista or higher, be sure that the "Symbolic Links"
 option was selected when installing Git prior to cloning this repository. If
 you're still seeing errors about files not being found it is likely because
 the symlink at ``api/client-server/definitions/event-schemas`` looks like a
-file. To correct the problem, open an Administrative/Elevated shell in your
+file. To correct the problem, open an Administrative/Elevated Command Prompt in your
 cloned matrix-doc directory and run the following::
 
   cd api\client-server\definitions
@@ -138,4 +140,4 @@ Issue tracking
 Issues with the Matrix specification are tracked in `GitHub
 <https://github.com/matrix-org/matrix-doc/issues>`_.
 
-See `meta/labels.rst <meta/labels.rst>`_ for notes on what the labels mean.
+See `meta/github-labels.rst <meta/github-labels.rst>`_ for notes on what the labels mean.

api/application-service/transactions.yaml

@@ -50,16 +50,15 @@ paths:
           x-example: "35"
         - in: body
           name: body
-          description: A list of events.
+          description: Transaction information
           schema:
             type: object
             example: {
               "events": [
                 {"$ref": "../../event-schemas/examples/m.room.member"},
-                {"$ref": "../../event-schemas/examples/m.room.message#m.text"}
+                {"$ref": "../../event-schemas/examples/m.room.message$m.text"}
               ]
             }
-            description: Transaction information
             properties:
               events:
                 type: array