Merge branch 'master' into travis/spec/MSC2320-identity-versions

Author: turt2live

CONTRIBUTING.rst

@@ -89,8 +89,8 @@ To create a changelog entry, create a file named in the format ``prNumber.type``
 the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``new`` - Used when adding new endpoints. Please have the file contents be the
-  method and route being added, surrounded in RST code tags. For example: ``POST
-  /accounts/whoami``
+  method and route being added, surrounded in markdown code tags. For example: \`POST
+  /accounts/whoami\`.
 
 * ``feature`` - Used when adding backwards-compatible changes to the API.
 
@@ -103,7 +103,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 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
-the style guide and and formatting must be done using Markdown.
+the style guide and formatting must be done using Markdown.
 
 Changes that do not change the spec, such as changes to the build script, formatting,
 CSS, etc should not get a news fragment.

README.md

@@ -2,10 +2,11 @@
 
 This repository contains the Matrix Specification, rendered at [spec.matrix.org](http://spec.matrix.org/).
 
-Developers looking to use Matrix should join [#matrix-dev:matrix.org](http://matrix.to/#/#matrix-dev:matrix.org)
+Developers looking to use Matrix should join [#matrix-dev:matrix.org](https://matrix.to/#/#matrix-dev:matrix.org)
 on Matrix for help.
 
-Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](http://matrix.to/#/#matrix-spec:matrix.org). We welcome contributions! See [CONTRIBUTING.rst](./CONTRIBUTING.rst) for details.
+Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org).
+We welcome contributions! See [CONTRIBUTING.rst](./CONTRIBUTING.rst) for details.
 
 ## Structure
 
@@ -21,7 +22,7 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as
   [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and
-  parse them. This is also where our
+  parse them. This is also where our Swagger/OpenAPI definitions and schemas are.
 
 * `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of
   a page: for example, whether it has header, footer, sidebar, and so on.
@@ -35,8 +36,8 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/themes`: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are
   supplied in a `/themes/$theme_name/layouts` directory. You can use a theme but customise it by providing your own
-  versions of any of the them layouts in the base `/layouts` directory. That is, if a theme provides
-  `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of this
+  versions of any of the theme layouts in the base `/layouts` directory. That is, if a theme provides
+  `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of the
   template will be used.
 
 It also has the following top-level file:
@@ -48,10 +49,9 @@ Additionally, the following directories may be of interest:
 
 * `/attic`: Here contains historical sections of specification and legacy drafts for the specification.
 * `/changelogs`: Various bits of changelog for the specification areas.
-* `/event-schemas`: [JSON Schema](http://json-schema.org/) definitions for the spec.
 * `/data-definitions`: Bits of structured data consumable by Matrix implementations.
 * `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
-* `/scripts`: Various scripts for generating the spec.
+* `/scripts`: Various scripts for generating the spec and validating its contents.
 * `/proposals`: Matrix Spec Change (MSC) proposals. See <https://spec.matrix.org/unstable/proposals/>.
 
 ## Authoring changes to the spec
@@ -62,7 +62,8 @@ place after an MSC has been accepted, not as part of a proposal itself.
 1. Install the extended version (often the OS default) of Hugo: <https://gohugo.io/getting-started/installing>
 2. Run `git submodule update --init --recursive` for good measure.
 3. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
-4. Run `npm run get-proposals` to seed the proposals data. This is not required.
+4. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
+   page and is not required.
 5. Run `hugo serve` to run a local webserver which builds whenever a file change is detected. If watching doesn't appear
    to be working for you, try `hugo serve --disableFastRender` instead.
 6. Edit the specification 🙂
@@ -73,18 +74,18 @@ Awesome. If you're looking at making design-related changes to the spec site, pl
 
 ## Building the specification
 
-If for some reason you're not a CI/CD system and want to render the spec yourself, follow the above steps for authoring
-changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the spec to `/spec`.
-If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"` to
-the `hugo -d "spec"` command.
+If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above
+steps for authoring changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the
+spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"`
+to the `hugo -d "spec"` command.
 
-For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`.
-To make use of the generated file, there are a number of options:
+For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file,
+there are a number of options:
 
-* It can be uploaded from your filesystem to an online editor/viewer such as
-  http://editor.swagger.io/
+* It can be uploaded from your filesystem to an online editor/viewer such as [on the swagger website](http://editor.swagger.io/).
 * You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation via an
-  online viewer; for example, at <http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json>
+  online viewer; for example, at <http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json>.
 * You can host the swagger UI yourself. See <https://github.com/swagger-api/swagger-ui#how-to-run> for advice on how to
   do so.
 

changelogs/client_server/newsfragments/3098.feature

@@ -0,0 +1 @@
+Add support for spoilers ([MSC2010](https://github.com/matrix-org/matrix-doc/pull/2010) and [MSC2557](https://github.com/matrix-org/matrix-doc/pull/2557)), and `color` attribute ([MSC2422](https://github.com/matrix-org/matrix-doc/pull/2422)).

changelogs/client_server/newsfragments/3099.clarification

@@ -0,0 +1 @@
+Clarify that event bodies are untrusted, as per [MSC2801](https://github.com/matrix-org/matrix-doc/pull/2801).

changelogs/client_server/newsfragments/3100.feature

@@ -0,0 +1 @@
+Add `<details>` and `<summary>` to the suggested HTML subset as per [MSC2184](https://github.com/matrix-org/matrix-doc/pull/2184).

changelogs/client_server/newsfragments/3116.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification.

changelogs/client_server/newsfragments/3127.clarification

@@ -0,0 +1 @@
+Fix the maximum event size restriction (65535 bytes -> 65536).

changelogs/client_server/newsfragments/3139.breaking

@@ -0,0 +1 @@
+Add `m.key.verification.ready` and `m.key.verification.done` to key verification framework as per [MSC2366](https://github.com/matrix-org/matrix-doc/pull/2366).

changelogs/client_server/newsfragments/3139.feature

@@ -0,0 +1 @@
+Add key verification using in-room messages as per [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241).

changelogs/client_server/newsfragments/3147.feature

@@ -0,0 +1 @@
+Add information about using SSSS for cross-signing and key backup.