Rename "recovery key" to "backup decryption key" (#1819)

Also, some other editorial improvements, including factoring out our two definitions of the same key encoding algorithm.

Co-authored-by: Travis Ralston <travisr@matrix.org>

.github/CODEOWNERS

@@ -0,0 +1 @@
+*       @matrix-org/spec-core-team

.github/ISSUE_TEMPLATE/config.yaml

@@ -1,4 +1,4 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
  - name: Matrix Spec Discussion
    url: "https://matrix.to/#/#matrix-spec:matrix.org"

.github/ISSUE_TEMPLATE/release.md

@@ -0,0 +1,35 @@
+---
+name: [SCT] Release checklist
+about: Used by the Spec Core Team to create a new release.
+title: 'Matrix 1.X'
+labels: 'release-blocker'
+assignees: ''
+
+---
+
+<!-- ------------------------------------------------------------------------ -->
+<!-- Please asssign the release coordinator (probably yourself) to this issue -->
+<!-- ------------------------------------------------------------------------ -->
+
+Date: **Thursday, May 25, 2023** <!-- CHANGE ME -->
+Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
+
+Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
+
+* [ ] Ensure the social media account holders are available for the release day.
+* [ ] Blog post written
+* [ ] Check for release blockers that may have been missed
+* [ ] Review/fix the changelog
+
+Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
+* [ ] Branch stuffs
+* [ ] Github release artifact
+* [ ] Published to spec.matrix.org
+* [ ] All links work
+* [ ] Publish blog post
+* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted
+* [ ] Post to Twitter/Mastodon
+* [ ] Close this issue
+
+Known release blockers:
+* [ ] <!-- Issue/PR link -->

.github/PULL_REQUEST_TEMPLATE/ready-proposal.md

@@ -1,19 +0,0 @@
----
-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

@@ -11,6 +11,6 @@ assignees: ''
 
 <!-- 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)
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#other-changes)

.github/PULL_REQUEST_TEMPLATE/wip-proposal.md

@@ -1,20 +0,0 @@
----
-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.

.github/_typos.toml

@@ -1,5 +1,5 @@
 [files]
-extend-exclude = ["/themes", "/attic", "/data-definitions", "*.css", "package-lock.json"]
+extend-exclude = ["/themes", "/attic", "/data-definitions", "*.css", "syntax.scss", "package-lock.json"]
 
 [default]
 check-filename = true
@@ -10,3 +10,4 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
+Iy = "Iy"

.github/workflows/checks.yaml

@@ -0,0 +1,18 @@
+# workflow steps that ought to pass on a PR, but shouldn't block a preview.
+
+name: "Checks"
+on:
+  pull_request:
+ 
+jobs:
+  check-newsfragments:
+    name: "🔎 Check that new newsfragments are valid"
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - run: scripts/check-newsfragments
+        env:
+          PULL_REQUEST_NUMBER: ${{ github.event.number }}

.github/workflows/main.yml

@@ -7,6 +7,10 @@ on:
       - v*
   pull_request:
   workflow_dispatch:
+  schedule:
+    # Run this workflow every day at 2am. This helps keep the page of
+    # current spec proposals up-to-date.
+    - cron: '0 2 * * *'
 
 jobs:
   validate-openapi:
@@ -14,32 +18,71 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
-      - name: "⚙️ npm"
-        working-directory: "./scripts"
-        run: |
-          npm install
+          node-version: '20'
       - name: "🔎 Run validator"
-        working-directory: "./scripts"
         run: |
-          node validator.js -s "../data/api/application-service"
-          node validator.js -s "../data/api/client-server"
-          node validator.js -s "../data/api/push-gateway"
+          npx @redocly/cli@latest lint data/api/*/*.yaml
 
-  check-examples:
+  check-event-examples:
     name: "🔎 Check Event schema examples"
     runs-on: ubuntu-latest
-    container: uhoreg/matrix-doc-build
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-event-schema-examples.py
+
+  check-openapi-examples:
+    name: "🔎 Check OpenAPI definitions examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-openapi-sources.py
+
+  check-schemas-examples:
+    name: "🔎 Check JSON Schemas inline examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
       - name: "🔎 Run validator"
         run: |
-          /env/bin/python scripts/check-event-schema-examples.py
+          python scripts/check-json-schemas.py
 
   calculate-baseurl:
     name: "⚙️ Calculate baseURL for later jobs"
@@ -56,76 +99,122 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo ::set-output name=baseURL::/
+              echo "baseURL=/" >> "$GITHUB_OUTPUT"
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
+              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
           else
-              echo ::set-output name=baseURL::/unstable
+              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
           fi
 
   build-openapi:
     name: "🐍 Build OpenAPI definitions"
     runs-on: ubuntu-latest
-    container: "python:3.9"
     needs: [calculate-baseurl]
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
-      - name: "📦 Asset creation"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
         run: |
-          python3 -m venv env && . env/bin/activate
           pip install -r scripts/requirements.txt
+      - name: "📦 Asset creation"
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            export RELEASE="${GITHUB_REF/refs\/tags\//}"
+          else
+            export RELEASE="unstable"
+          fi
           # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api application-service \
+            -r "$RELEASE" \
             -o spec/application-service-api/api.json
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api client-server \
+            -r "$RELEASE" \
             -o spec/client-server-api/api.json
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api push-gateway \
+            -r "$RELEASE" \
             -o spec/push-gateway-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --api server-server \
+              -r "$RELEASE" \
+              -o spec/server-server-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
 
+  generate-changelog:
+    name: "📢 Run towncrier for changelog"
+    # skip for builds of git tags
+    if: "!startsWith(github.ref, 'refs/tags/')"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+      - name: "➕ Install towncrier"
+        run: "pip install 'towncrier'"
+      - name: "Generate changelog"
+        run: ./scripts/generate-changelog.sh vUNSTABLE
+      - name: "📤 Artifact upload"
+        uses: actions/upload-artifact@v4
+        with:
+          name: changelog-artifact
+          path: content/changelog/vUNSTABLE.md
+
   build-spec:
     name: "📖 Build the spec"
     runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-openapi]
+    needs: [calculate-baseurl, build-openapi, generate-changelog]
+    # run even if generate-changelog was skipped
+    if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.85.0'
+          hugo-version: '0.113.0'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
-        with:
-          submodules: 'recursive'
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
           npm run get-proposals
+      - name: "📥 Download generated changelog"
+        if: "needs.generate-changelog.result == 'success'"
+        uses: actions/download-artifact@v4
+        with:
+          name: changelog-artifact
+          path: content/changelog
       - name: "⚙️ hugo"
         run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
-
       # We manually unpack the spec OpenAPI definition JSON to the website tree
       # to make it available to the world in a canonical place:
       # https://spec.matrix.org/latest/client-server-api/api.json
       # Works for /unstable/ and /v1.1/ as well.
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -135,11 +224,39 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
 
+  htmlcheck:
+    name: "🔎 Validate generated HTML"
+    runs-on: ubuntu-latest
+    needs: [calculate-baseurl, build-spec]
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+
+      - name: "📥 Fetch built spec"
+        uses: actions/download-artifact@v4
+        with:
+          name: spec-artifact
+
+      - name: "📝 Unpack the spec"
+        # we have to unpack it into the right path given the baseurl, so that the
+        # links are correct.
+        # eg if baseurl is `/unstable`, we want to put the site in `spec/unstable`.
+        run: |
+          mkdir -p "spec${baseURL}"
+          tar -C "spec${baseURL}" --strip-components=1 -xvzf spec.tar.gz
+        env:
+          baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
+
+      - name: "Run htmltest"
+        uses: wjdp/htmltest-action@master
+        with:
+          config: .htmltest.yaml
+
   build-historical-spec:
     name: "📖 Build the historical backup spec"
     runs-on: ubuntu-latest
@@ -147,18 +264,17 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.85.0'
+          # Cannot build the spec with Hugo 0.125.0 because of https://github.com/google/docsy/issues/1930
+          hugo-version: '0.124.1'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
-        with:
-          submodules: 'recursive'
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
@@ -170,7 +286,7 @@ jobs:
           hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -180,7 +296,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -32,10 +32,10 @@ jobs:
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
                jq -r '.[] | .number')
           echo "PR number: $pr_number"
-          echo "::set-output name=prnumber::$pr_number"
+          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@af92a8455a59214b7b932932f2662fdefbd78126 # v2.15.0
+        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
@@ -46,8 +46,7 @@ jobs:
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        # v1.2.2
-        uses: nwtgck/actions-netlify@f517512ae75beec8896aa7b027c1c72f01816200
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -0,0 +1,42 @@
+name: Release packages
+on:
+  release:
+    types: [published]
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+  # Releases to npm after bumping the package.json version from 0.0.0 to $TAG.0 as the tags only contain MAJOR.MINOR
+  npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    if: github.event.release.prerelease == false
+    defaults:
+      run:
+        working-directory: packages/npm
+    steps:
+      - name: 🧮 Checkout code
+        uses: actions/checkout@v4
+
+      - name: 🔧 Yarn cache
+        uses: actions/setup-node@v4
+        with:
+          cache: "yarn"
+          cache-dependency-path: packages/npm/yarn.lock
+          registry-url: "https://registry.npmjs.org"
+
+      - name: 🔨 Install dependencies
+        run: "yarn install --frozen-lockfile"
+
+      # We bump the package.json version to git, we just need it for publish to do the right thing
+      - name: 🎖 Bump package.json version
+        run: "yarn version --new-version ${VERSION#v} --no-git-tag-version"
+        env:
+          VERSION: ${{ github.event.release.tag_name }}.0
+
+      - name: 🚀 Publish to npm
+        id: npm-publish
+        uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
+        with:
+          token: ${{ secrets.NPM_TOKEN }}
+          package: packages/npm
+          access: public
+          ignore-scripts: false

.github/workflows/spell-check.yaml

@@ -1,5 +1,9 @@
 name: Spell Check
-on: [pull_request]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 
 jobs:
   run:
@@ -7,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Actions Repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@master
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
-        config: ${{github.workspace}}/.github/_typos.toml
+        config: ${{github.workspace}}/.github/_typos.toml

.gitignore

@@ -2,7 +2,7 @@ node_modules
 /data/msc
 /env*
 /resources
-/scripts/swagger
+/scripts/openapi
 /scripts/tmp
 /hugo-config.toml
 /public

.gitmodules

@@ -1,4 +0,0 @@
-[submodule "themes/docsy"]
-	path = themes/docsy
-	url = https://github.com/matrix-org/docsy.git
-	branch = master

.htmltest.yaml

@@ -0,0 +1,6 @@
+# config file for htmltest. This is used by one of the checks in Github
+# Actions.
+
+IgnoreDirectoryMissingTrailingSlash: true
+DirectoryPath: spec
+CheckExternal: false

CONTRIBUTING.rst

@@ -1,5 +1,5 @@
-Contributing to matrix-doc
-==========================
+Contributing to matrix-spec
+===========================
 
 Everyone is welcome to contribute to the Matrix specification!
 
@@ -9,14 +9,10 @@ Code style
 ----------
 
 The documentation style is described at
-https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
+https://github.com/matrix-org/matrix-spec/blob/main/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.md.
-
-Matrix-doc workflows
---------------------
+Matrix-spec workflows
+---------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -27,9 +23,7 @@ server before they can be documented in the specification. This process can take
 some time to complete.
 
 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.
+`proposals process <https://matrix.org/docs/spec/proposals>`_.
 
 Other changes
 ~~~~~~~~~~~~~
@@ -42,12 +36,12 @@ following:
 
 * 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).
+  <https://github.com/matrix-org/matrix-spec/labels/spec-omission>`_ label).
 
 * Likewise, corrections to the specification, to fix situations where, in
   practice, servers and clients behave differently to the specification,
   including anything with the `spec-bug
-  <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
+  <https://github.com/matrix-org/matrix-spec/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-spec:matrix.org`_.)
@@ -55,7 +49,7 @@ following:
 * 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>`_
+  `clarification <https://github.com/matrix-org/matrix-spec/labels/clarification>`_
   label.
 
   For example, areas where the specification is unclear do not require a proposal
@@ -78,12 +72,16 @@ ask.
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-All API specifications require a changelog entry. Adding to the changelog can only
+All changes to the contents of this repository 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
-under ``changelogs/client_server/newsfragments``.
+The changelog is managed by `Towncrier <https://github.com/twisted/towncrier>`_ in the
+form of "news fragments". Depending on which API you changed, an entry should be added to
+each relevant API's ``newsfragments`` directory. A directory exists for each API under
+``changelogs/``. For instance, news fragments for the client-server API are stored
+under ``changelogs/client_server/newsfragments``. Any changes to the repository that do
+not affect the spec content itself, such as changes to the build script, formatting, CSS,
+etc. should be documented under ``changelogs/internal/newsfragments``.
 
 To create a changelog entry, create a file named in the format ``prNumber.type`` in
 the ``newsfragments`` directory. The ``type`` can be one of the following:
@@ -105,13 +103,10 @@ 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 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.
-
 Sign off
 --------
 
-We ask that everybody who contributes to their project signs off their
+We ask that everybody who contributes to this project signs off their
 contributions, as explained below.
 
 We follow a simple 'inbound=outbound' model for contributions: the act of
@@ -121,11 +116,10 @@ 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
-same lightweight approach that the Linux Kernel
-(https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker
-(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
-projects use: the DCO (Developer Certificate of Origin:
-http://developercertificate.org/). This is a simple declaration that you wrote
+same lightweight approach used by the `Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_,
+`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
+projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
+(DCO). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
 
     Developer Certificate of Origin
@@ -173,3 +167,15 @@ include the line in your commit or pull request comment::
 can't be accepted. Git makes this trivial - just use the -s flag when you do
 ``git commit``, having first set ``user.name`` and ``user.email`` git configs
 (which you should have done anyway :)
+
+Private sign off
+~~~~~~~~~~~~~~~~
+
+If you would like to provide your legal name privately to the Matrix.org
+Foundation (instead of in a public commit or comment), you can do so by emailing
+your legal name and a link to the pull request to dco@matrix.org. It helps to
+include "sign off" or similar in the subject line. You will then be instructed
+further.
+
+Once private sign off is complete, doing so for future contributions will not
+be required.

README.md

@@ -1,6 +1,6 @@
 # Matrix Specification
 
-This repository contains the Matrix Specification, rendered at [spec.matrix.org](http://spec.matrix.org/).
+This repository contains the Matrix Specification. The current release version is rendered at https://spec.matrix.org, while the latest available build of the `main` branch is at https://spec.matrix.org/unstable.
 
 Developers looking to use Matrix should join [#matrix-dev:matrix.org](https://matrix.to/#/#matrix-dev:matrix.org)
 on Matrix for help.
@@ -22,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 Swagger/OpenAPI definitions and schemas are.
+  parse them. This is also where our 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.
@@ -52,7 +52,7 @@ Additionally, the following directories may be of interest:
 * `/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 and validating its contents.
-* `/proposals`: Matrix Spec Change (MSC) proposals. See <https://spec.matrix.org/unstable/proposals/>.
+* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions.
 
 ## Authoring changes to the spec
 
@@ -61,20 +61,19 @@ 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>. Note that at least Hugo
-   v0.74 is required.
+   v0.113.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
    to process the SCSS.)
-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 proposal data. This is merely for populating the content of the "Spec Change Proposals"
+2. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
+3. 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` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
+4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
    klakegg/hugo:ext 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
    adding `--disableFastRender` to the commandline.
-6. Edit the specification 🙂
+5. Edit the specification 🙂
 
 We use a highly customized [Docsy](https://www.docsy.dev/) theme for our generated site, which uses Bootstrap and Font
 Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in
@@ -87,18 +86,16 @@ steps for authoring changes to the specification and instead of `hugo serve` run
 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,
+For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+and finally `python ./scripts/dump-openapi.py` to generate it to `./scripts/openapi/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 [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>.
-* 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.
+* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
+* You can run a local HTTP server by running `./scripts/openapi-http-server.py`, and then view the documentation by
+  opening `./scripts/openapi-preview.html` in your browser.
 
 ## Issue tracking
 
-Specification issues are tracked on github at <https://github.com/matrix-org/matrix-doc/issues>.
+Specification issues are tracked on github at <https://github.com/matrix-org/matrix-spec/issues>.
 
 See [meta/github-labels.rst](./meta/github-labels.rst) for information on what the labels mean.

assets/scss/_styles_project.scss

@@ -18,8 +18,19 @@ limitations under the License.
 Custom SCSS for the Matrix spec
 */
 
-@import "variables_project";
-@import "variables";
+/* Import the CSS classes for the syntax highlighter.
+ *
+ * This is generated with:
+ *
+ *    hugo gen chromastyles --style=tango > assets/scss/syntax.scss
+ */
+@import "syntax.scss";
+
+/* Workaround for https://github.com/google/docsy/issues/1116:
+ * fix scroll-anchoring */
+.td-outer {
+    height: auto;
+}
 
 /* Overrides for the navbar */
 .td-navbar {
@@ -29,10 +40,17 @@ Custom SCSS for the Matrix spec
   .navbar-brand {
     font-size: 1.1rem;
 
+    /* Allow the text to wrap if it is wider than the viewport */
+    text-align: center;
+    white-space: normal;
+
     .navbar-version {
       color: $secondary;
     }
+  }
 
+  .nav-link {
+    font-weight: normal;
   }
 
   a {
@@ -41,6 +59,11 @@ Custom SCSS for the Matrix spec
 }
 
 /* Styles for the sidebar nav */
+.td-sidebar {
+    /* don't attempt to use the sidebar (or things in it) as a scroll anchor. */
+    overflow-anchor: none;
+}
+
 .td-sidebar-nav {
   scroll-behavior: smooth;
   overscroll-behavior: contain;
@@ -49,9 +72,8 @@ Custom SCSS for the Matrix spec
     margin-top: 1rem;
   }
 
-  &>.td-sidebar-nav__section > li > a.td-sidebar-link {
-      font-weight: $font-weight-bold;
-      font-size: 1.3rem;
+  .td-sidebar-nav__section .ul-1 ul {
+    padding-left: 0;
   }
 
   /* This is to make the width of the items that have sub-items (like room versions)
@@ -60,12 +82,20 @@ Custom SCSS for the Matrix spec
     padding-right: 0 !important;
   }
 
-  a.indent-1 {
+  .ul-1 > li > a {
     padding-left: 1rem !important;
   }
 
-  a.indent-2 {
-    padding-left: 2rem;
+  .ul-2 > li > a {
+    padding-left: 2rem !important;
+  }
+
+  a.td-sidebar-link.tree-root {
+    color: $gray-800;
+    font-weight: $font-weight-bold;
+    font-size: 1.3rem;
+    margin-bottom: 0;
+    border-bottom: none;
   }
 
   a, a.td-sidebar-link {
@@ -84,12 +114,11 @@ Custom SCSS for the Matrix spec
 
     &.active, &active:hover {
       background-color: $secondary-background;
-      font-weight: $font-weight-normal;
     }
   }
 }
 
-@media (min-width: 768px) {
+@include media-breakpoint-up(md) {
   @supports (position: sticky) {
     .td-sidebar-nav {
       /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
@@ -146,18 +175,19 @@ footer {
 
 }
 
-/* Adjust heading anchors for site header */
-.td-content {
-  &> h2,
-  &> h3,
-  &> h4,
-  &> h5,
-  &> h6,
-  .rendered-data h1 {
-    scroll-margin-top: 5rem;
+/* Remove some padding before the main content, when the sidebar is disabled */
+.td-main main {
+  @include media-breakpoint-down(md) {
+    padding-top: 0;
   }
 }
 
+/* Adjust the scroll margin for everything in the main content, so that
+ * it doesn't disappear behind the header bar */
+.td-content * {
+  scroll-margin-top: 5.5rem;
+}
+
 /* Styles for the table of contents */
 #toc {
   padding-top: .5rem;
@@ -247,17 +277,47 @@ footer {
     border-left-width: 5px;
     background: $warning-background;
   }
+
+  // XXX: See the added-in-paragraph.html shortcode for more information on these styles.
+  &.added-in-paragraph {
+    // Remove the padding and margin to remove the box look
+    margin: 0 !important; // !important on both to override table-related rules
+    padding: 0 !important;
+
+    // Make pairs of "added-in" and content inline to each other. We do pairs so authors can
+    // describe two paragraphs with added-in prefixes within a single box, reducing DOM
+    // complexity. Each paragraph is expected to be prefixed with an added-in, however.
+    //
+    // XXX: We assume the added-in and text will be rendered as paragraph elements.
+    > p {
+      display: inline;
+    }
+    > p:nth-child(2n) { // "even" rule to target just the content paragraphs
+      // Force a paragraph break after the content (insert a couple <br /> tags)
+      &::after {
+        content: '\A\A';
+        white-space: pre;
+      }
+    }
+  }
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
-.rendered-data {
-  margin: 1rem 0 3rem 0;
+.td-content .rendered-data {
+  background-color: $secondary-lightest-background;
+  padding: 0.85rem;
+  margin: 0.85rem 0;
 
   details {
-
     summary {
-      padding: .5rem 0;
-      list-style-position: outside;
+      h1 {
+        margin: 0;
+        /* Ensure the disclosure control is vertically centred with the header text. */
+        vertical-align: middle;
+      }
+    }
+    p {
+      max-width: 80%;
     }
   }
 
@@ -291,27 +351,52 @@ footer {
     margin: 1.5rem 0 .75rem 0;
   }
 
-  h2 + table, h3 + table, h3 + div.highlight {
-    margin-top: 0;
-  }
-
   hr {
     border-bottom: 2px solid $dark;
     margin-bottom: 1.5rem;
   }
 
-  p {
-    max-width: 80%;
-  }
-
   p code, table code {
-    background-color: $white;
+    background-color: transparent;
   }
 
   table {
-    table-layout: fixed;
-    width: 100%;
-    margin: 4rem 0;
+    @media (max-width: 800px) {
+      /* Docsy by default applies `overflow-x: auto;` to tables, which
+       * results in annoying horizontal scrolling on mobile, so we instead
+       * switch to a fixed table layout on a narrow browser width.
+       * (On a wider width the default auto table-layout provides better readability.)
+       *
+       * Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
+       * tables with a "display" property of "block".
+       * However, for "table-layout: fixed" to be effective, an element must have a
+       * "display" property of "table".
+       *
+       * Thus, we override the "display" property here. This may no longer be necessary once
+       * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
+       * For more details, see
+       * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
+      display: table;
+      table-layout: fixed;
+      width: 100%;
+
+      .col-name, .col-type, .col-status {
+        width: 25%;
+      }
+
+      .col-description {
+        width: 50%;
+      }
+
+      .col-status-description {
+        width: 75%;
+      }
+    }
+
+    // add some space between two tables when they are right next to each other
+    & + table {
+        margin-top: 4rem;
+    }
 
     caption {
       caption-side: top;
@@ -322,42 +407,61 @@ footer {
 
     th, td, caption {
       padding: 1rem;
+      border-top: 1px $table-border-color solid;
     }
 
-    th {
-      background-color: $white;
-    }
+    &.object-table, &.response-table, &.content-type-table {
+        border: 1px $table-border-color solid;
 
-    caption, tr {
-      background-color: $table-row-default;
-    }
+        caption {
+            // the caption is outside the table's border box,
+            // so we have to give it its own border.
+            border: 1px $table-border-color solid;
 
-    tr:nth-child(even) {
-      background-color: $table-row-alternate;
+            // ... but avoid double border between caption and table
+            border-bottom: 0;
+
+            background-color: $secondary-lighter-background;
+        }
+
+        tbody tr {
+            --bs-table-striped-bg: #{$secondary-lighter-background};
+        }
     }
 
     &.basic-info, &.basic-info th, &.basic-info td {
       table-layout: fixed;
       margin: 1rem 0 .5rem 0;
-      background-color: $white;
     }
 
     &.basic-info th {
       width: 15rem;
     }
 
-    .col-name, .col-type, .col-status {
-      width: 25%;
-    }
+    /* Arrange rows vertically when horizontal space is constrained to avoid overflowing */
+    @include media-breakpoint-down(sm) {
+      /* Make cells full width without vertical margin */
+      &.basic-info th, &.basic-info td {
+        width: 100%;
+        display: inline-block;
+        margin-top: 0;
+        margin-bottom: 0;
+      }
 
-    .col-description {
-      width: 50%;
-    }
+      /* Remove border and padding between header & data cells to make them appear like a single cell */
+      &.basic-info td {
+        padding-top: 0;
+        border-top: none;
+      }
+      &.basic-info th {
+        border-bottom: none;
+      }
 
-    .col-status-description {
-      width: 75%;
+      /* Remove top border on all but the first header cell to prevent double borders between rows */
+      &.basic-info tr + tr th {
+        border-top: none;
+      }
     }
-
   }
 
   pre {
@@ -402,12 +506,18 @@ of .td-content. This applies the same style to any blockquotes that descend from
 Make padding symmetrical (this selector is used in the default styles to apply padding-left: 3rem)
 */
 .pl-md-5, .px-md-5 {
-  padding-right: 3rem;
+  @include media-breakpoint-up(md) {
+    padding-right: 3rem;
+  }
 }
 
 /* Adjust default styles for info banner */
 .pageinfo-primary {
-  max-width: 80%;
+  @include media-breakpoint-up(lg) {
+    max-width: 80%;
+  }
+  margin-top: 0;
+  margin-right: 0;
   margin-left: 0;
   border: 0;
   border-left: solid 5px $secondary;
@@ -421,8 +531,42 @@ Make padding symmetrical (this selector is used in the default styles to apply p
   padding-left: 100px;
 }
 
-/* Full-width tables */
-.td-content > table {
-  width: 100%;
-  display: table;
+/* Adjust the styling of definition lists. */
+
+/* Add a little spacing between the term and its definition. */
+dt {
+   margin-bottom: 0.15rem;
+}
+
+/* _reboot.scss deliberately sets margin-left to 0. Undo this. */
+dd {
+  margin-left: 2rem;
 }
+
+/* docsy's _code.scss does only styles <code> elements matching
+ * .td-content { p code, li > code, table code }.
+ * Copy those styles here to apply to code <elements> in definition terms too. */
+
+.td-content {
+  dt code {
+    color: inherit;
+    padding: 0.2em 0.4em;
+    margin: 0;
+    font-size: 85%;
+    word-break: normal;
+    background-color: rgba($black, 0.05);
+    border-radius: 0.25rem;  // was $border-radius, but that var isn't accessible here.
+  }
+}
+
+/* Style for breadcrumbs */
+.td-breadcrumbs {
+  padding: .75rem 1rem;
+  background-color: #eee;
+  border-radius: .25rem;
+  margin-bottom: 1rem;
+
+  .breadcrumb {
+    margin: 0;
+  }
+}

assets/scss/_variables_project.scss

@@ -20,7 +20,7 @@ $dark: #333;
 $gray-100: #FBFBFB;
 
 $secondary-background: #E5F5FB;
-$secondary-lighter-background: #F4FaFC;
+$secondary-lighter-background: #F4FAFC;
 $secondary-lightest-background: #FBFDFD;
 
 
@@ -30,12 +30,25 @@ $note: $secondary;
 $note-background: $secondary-background;
 $warning-background: #FFE0E0;
 
-$table-row-alternate: $secondary-lightest-background;
-$table-row-default: $secondary-lighter-background;
+// colours for definition tables.
+// the border colour matches that used for "highlight" divs
+$table-border-color: rgba(black, .125);
+$table-bg: $secondary-lightest-background;
+
+/* Configure docsy to use the default system fonts instead of Google Fonts.
+ * See https://www.docsy.dev/docs/adding-content/lookandfeel/#fonts */
+$td-enable-google-fonts: false;
 
 /*
- Opt to serve fonts locally by overriding web-font-path to be a non-google fonts URL.
- This is only possible with our modified docsy theme: https://github.com/matrix-org/docsy
+ * Replace the default font with Inter.
+ *
+ * The $font-family-sans-serif definition here overrides the default value set by docsy:
+ * https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68
+ * and adds "Inter" to the front.
+ *
+ * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html.
  */
-$web-font-path: "../css/fonts/Inter.css";
-$google_font_name: "Inter";
+$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+
+// Disable smooth scrolling as it makes TOC highlighting jump during the transition.
+$enable-smooth-scroll: false;

assets/scss/syntax.scss

@@ -0,0 +1,82 @@
+/* Background */ .chroma { background-color: #f8f8f8 }
+/* Other */ .chroma .x { color: #000000 }
+/* Error */ .chroma .err { color: #a40000 }
+/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
+/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
+/* LineHighlight */ .chroma .hl { display: block; width: 100%;background-color: #ffffcc }
+/* LineNumbersTable */ .chroma .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
+/* LineNumbers */ .chroma .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
+/* Keyword */ .chroma .k { color: #204a87; font-weight: bold }
+/* KeywordConstant */ .chroma .kc { color: #204a87; font-weight: bold }
+/* KeywordDeclaration */ .chroma .kd { color: #204a87; font-weight: bold }
+/* KeywordNamespace */ .chroma .kn { color: #204a87; font-weight: bold }
+/* KeywordPseudo */ .chroma .kp { color: #204a87; font-weight: bold }
+/* KeywordReserved */ .chroma .kr { color: #204a87; font-weight: bold }
+/* KeywordType */ .chroma .kt { color: #204a87; font-weight: bold }
+/* Name */ .chroma .n { color: #000000 }
+/* NameAttribute */ .chroma .na { color: #c4a000 }
+/* NameBuiltin */ .chroma .nb { color: #204a87 }
+/* NameBuiltinPseudo */ .chroma .bp { color: #3465a4 }
+/* NameClass */ .chroma .nc { color: #000000 }
+/* NameConstant */ .chroma .no { color: #000000 }
+/* NameDecorator */ .chroma .nd { color: #5c35cc; font-weight: bold }
+/* NameEntity */ .chroma .ni { color: #ce5c00 }
+/* NameException */ .chroma .ne { color: #cc0000; font-weight: bold }
+/* NameFunction */ .chroma .nf { color: #000000 }
+/* NameFunctionMagic */ .chroma .fm { color: #000000 }
+/* NameLabel */ .chroma .nl { color: #f57900 }
+/* NameNamespace */ .chroma .nn { color: #000000 }
+/* NameOther */ .chroma .nx { color: #000000 }
+/* NameProperty */ .chroma .py { color: #000000 }
+/* NameTag */ .chroma .nt { color: #204a87; font-weight: bold }
+/* NameVariable */ .chroma .nv { color: #000000 }
+/* NameVariableClass */ .chroma .vc { color: #000000 }
+/* NameVariableGlobal */ .chroma .vg { color: #000000 }
+/* NameVariableInstance */ .chroma .vi { color: #000000 }
+/* NameVariableMagic */ .chroma .vm { color: #000000 }
+/* Literal */ .chroma .l { color: #000000 }
+/* LiteralDate */ .chroma .ld { color: #000000 }
+/* LiteralString */ .chroma .s { color: #4e9a06 }
+/* LiteralStringAffix */ .chroma .sa { color: #4e9a06 }
+/* LiteralStringBacktick */ .chroma .sb { color: #4e9a06 }
+/* LiteralStringChar */ .chroma .sc { color: #4e9a06 }
+/* LiteralStringDelimiter */ .chroma .dl { color: #4e9a06 }
+/* LiteralStringDoc */ .chroma .sd { color: #8f5902; font-style: italic }
+/* LiteralStringDouble */ .chroma .s2 { color: #4e9a06 }
+/* LiteralStringEscape */ .chroma .se { color: #4e9a06 }
+/* LiteralStringHeredoc */ .chroma .sh { color: #4e9a06 }
+/* LiteralStringInterpol */ .chroma .si { color: #4e9a06 }
+/* LiteralStringOther */ .chroma .sx { color: #4e9a06 }
+/* LiteralStringRegex */ .chroma .sr { color: #4e9a06 }
+/* LiteralStringSingle */ .chroma .s1 { color: #4e9a06 }
+/* LiteralStringSymbol */ .chroma .ss { color: #4e9a06 }
+/* LiteralNumber */ .chroma .m { color: #0000cf; font-weight: bold }
+/* LiteralNumberBin */ .chroma .mb { color: #0000cf; font-weight: bold }
+/* LiteralNumberFloat */ .chroma .mf { color: #0000cf; font-weight: bold }
+/* LiteralNumberHex */ .chroma .mh { color: #0000cf; font-weight: bold }
+/* LiteralNumberInteger */ .chroma .mi { color: #0000cf; font-weight: bold }
+/* LiteralNumberIntegerLong */ .chroma .il { color: #0000cf; font-weight: bold }
+/* LiteralNumberOct */ .chroma .mo { color: #0000cf; font-weight: bold }
+/* Operator */ .chroma .o { color: #ce5c00; font-weight: bold }
+/* OperatorWord */ .chroma .ow { color: #204a87; font-weight: bold }
+/* Punctuation */ .chroma .p { color: #000000; font-weight: bold }
+/* Comment */ .chroma .c { color: #8f5902; font-style: italic }
+/* CommentHashbang */ .chroma .ch { color: #8f5902; font-style: italic }
+/* CommentMultiline */ .chroma .cm { color: #8f5902; font-style: italic }
+/* CommentSingle */ .chroma .c1 { color: #8f5902; font-style: italic }
+/* CommentSpecial */ .chroma .cs { color: #8f5902; font-style: italic }
+/* CommentPreproc */ .chroma .cp { color: #8f5902; font-style: italic }
+/* CommentPreprocFile */ .chroma .cpf { color: #8f5902; font-style: italic }
+/* Generic */ .chroma .g { color: #000000 }
+/* GenericDeleted */ .chroma .gd { color: #a40000 }
+/* GenericEmph */ .chroma .ge { color: #000000; font-style: italic }
+/* GenericError */ .chroma .gr { color: #ef2929 }
+/* GenericHeading */ .chroma .gh { color: #000080; font-weight: bold }
+/* GenericInserted */ .chroma .gi { color: #00a000 }
+/* GenericOutput */ .chroma .go { color: #000000; font-style: italic }
+/* GenericPrompt */ .chroma .gp { color: #8f5902 }
+/* GenericStrong */ .chroma .gs { color: #000000; font-weight: bold }
+/* GenericSubheading */ .chroma .gu { color: #800080; font-weight: bold }
+/* GenericTraceback */ .chroma .gt { color: #a40000; font-weight: bold }
+/* GenericUnderline */ .chroma .gl { color: #000000; text-decoration: underline }
+/* TextWhitespace */ .chroma .w { color: #f8f8f8; text-decoration: underline }

attic/drafts/model/rooms.rst

@@ -246,7 +246,7 @@ anyway.
 In this arrangement there is now a room with both users may join but neither has
 the power to invite any others. Both users now have the confidence that (at
 least within the messaging system itself) their messages remain private and
-cannot later be provably leaked to a third party. They can freely set the topic
+cannot later be provably leaked to a third-party. They can freely set the topic
 or name if they choose and add or edit any other state of the room. The update
 powerlevel of each of these fixed properties should be 1, to lock out the users
 from being able to alter them.

attic/drafts/model/third-party-id.rst

@@ -1,9 +1,9 @@
 ======================
-Third Party Identities
+Third-party Identities
 ======================
 
-A description of how email addresses, mobile phone numbers and other third
-party identifiers can be used to authenticate and discover users in Matrix.
+A description of how email addresses, mobile phone numbers and other third-party
+identifiers can be used to authenticate and discover users in Matrix.
 
 
 Overview
@@ -15,16 +15,16 @@ and phone numbers for contacts in their address book. They want to communicate
 with those contacts in Matrix without manually exchanging a Matrix User ID with 
 them.
 
-Third Party IDs
+Third-party IDs
 ---------------
 
 [[TODO(markjh): Describe the format of a 3PID]]
 
 
-Third Party ID Associations
+Third-party ID Associations
 ---------------------------
 
-An Associaton is a binding between a Matrix User ID and a Third Party ID (3PID).
+An Associaton is a binding between a Matrix User ID and a Third-party ID (3PID).
 Each 3PID can be associated with one Matrix User ID at a time.
 
 [[TODO(markjh): JSON format of the association.]]

changelogs/appendices/newsfragments/1791.clarification

@@ -0,0 +1 @@
+Define 'Opaque Identifier Grammar'.

changelogs/appendices/newsfragments/1819.clarification

@@ -0,0 +1 @@
+Define common cryptographic key representation.

changelogs/appendices/newsfragments/3171.feature

@@ -1 +0,0 @@
-Describe "Common Namespaced Identifier Grammar" as per [MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758).

changelogs/appendices/newsfragments/3608.feature

@@ -1 +0,0 @@
-Describe the `matrix:` URI scheme as per [MSC2312](https://github.com/matrix-org/matrix-doc/pull/2312).

changelogs/application_service/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/application_service/newsfragments/1810.clarification

@@ -0,0 +1 @@
+Clarify that appservices should be notified of events relating to the sender_localpart user.

changelogs/application_service/newsfragments/3658.clarification

@@ -1 +0,0 @@
-Distinguish between "federation" event format as exchanged by the Federation API, and the "client" event formats as used in the client-server and AS APIs.

changelogs/application_service/newsfragments/3674.clarification

@@ -1 +0,0 @@
-Fix the rendering of the responses for various API endpoints.

changelogs/application_service/newsfragments/3675.clarification

@@ -1 +0,0 @@
-Correct the documentation for the response value for `GET /_matrix/app/v1/thirdparty/protocol/{protocol}`.

changelogs/client_server/newsfragments/1755.clarification

@@ -0,0 +1 @@
+Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291).

changelogs/client_server/newsfragments/1757.feature

@@ -0,0 +1 @@
+Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).

changelogs/client_server/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/client_server/newsfragments/1776.clarification

@@ -0,0 +1 @@
+Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response.

changelogs/client_server/newsfragments/1808.clarification

@@ -0,0 +1 @@
+Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).

changelogs/client_server/newsfragments/1812.feature

@@ -0,0 +1 @@
+Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692).

changelogs/client_server/newsfragments/1813.clarification

@@ -0,0 +1 @@
+Use `patternProperties` in more places with supported formats.

changelogs/client_server/newsfragments/1819.clarification

@@ -0,0 +1 @@
+Rename "recovery key" to "backup decryption key".

changelogs/client_server/newsfragments/3324.feature

@@ -1 +0,0 @@
-Extend `/_matrix/client/r0/login` to accept a `m.login.appservice`, as per [MSC2778](https://github.com/matrix-org/matrix-doc/pull/2778).

changelogs/client_server/newsfragments/3387.feature

@@ -1 +0,0 @@
-Add support for `restricted` rooms as per [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083), [MSC3289](https://github.com/matrix-org/matrix-doc/pull/3289), and [MSC3375](https://github.com/matrix-org/matrix-doc/pull/3375).

changelogs/client_server/newsfragments/3481.clarification

@@ -1 +0,0 @@
-Make `AesHmacSha2KeyDescription` consistent with `KeyDescription` in marking `name` as optional.

changelogs/client_server/newsfragments/3482.clarification

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

changelogs/client_server/newsfragments/3492.clarification

@@ -1 +0,0 @@
-Explicitly mention RFC5870 in the definition of `m.location` events

changelogs/client_server/newsfragments/3495.clarification

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

changelogs/client_server/newsfragments/3509.clarification

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

changelogs/client_server/newsfragments/3524.breaking

@@ -1 +0,0 @@
-The `prev_content` field is now returned inside the `unsigned` property of events, rather than at the top level, as per [MSC3442](https://github.com/matrix-org/matrix-doc/pull/3442).

changelogs/client_server/newsfragments/3530.clarification

@@ -1 +0,0 @@
-Add `403 M_FORBIDDEN` error code to `/profile/{userId}` as per [MSC3550](https://github.com/matrix-org/matrix-doc/pull/3550).

changelogs/client_server/newsfragments/3535.clarification

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

changelogs/client_server/newsfragments/3543.clarification

@@ -1 +0,0 @@
-Clarify the description of the `/sync` API, including a fix to an ASCII art diagram.

changelogs/client_server/newsfragments/3562.clarification

@@ -1 +0,0 @@
-Clarify that `base_url` in client `well_known` may or may not include trailing slash.

changelogs/client_server/newsfragments/3573.clarification

@@ -1 +0,0 @@
-Clarify which signature to check when decrypting `m.olm.v1.curve25519-aes-sha2` messages.

changelogs/client_server/newsfragments/3591.clarification

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

changelogs/client_server/newsfragments/3601.clarification

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

changelogs/client_server/newsfragments/3605.feature.1

@@ -1 +0,0 @@
-Add `is_guest` to `/account/whoami` as per [MSC3069](https://github.com/matrix-org/matrix-doc/pull/3069).

changelogs/client_server/newsfragments/3605.feature.2

@@ -1 +0,0 @@
-Expand guest access to sending any room event and state event as per [MSC3419](https://github.com/matrix-org/matrix-doc/pull/3419).

changelogs/client_server/newsfragments/3606.clarification

@@ -1 +0,0 @@
-Clarify what "Stripped State" is and what purpose it serves, as per [MSC3173](https://github.com/matrix-org/matrix-doc/pull/3173).

changelogs/client_server/newsfragments/3610.feature

@@ -1 +0,0 @@
-Add Spaces and room types as per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) and [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946).

changelogs/client_server/newsfragments/3610.new

@@ -1 +0,0 @@
-Add the Space Hierarchy API (`GET /_matrix/client/v1/rooms/{roomId}/hierarchy`) as per [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946).

changelogs/client_server/newsfragments/3611.clarification

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

changelogs/client_server/newsfragments/3614.feature

@@ -1 +0,0 @@
-Add new `m.set_displayname`, `m.set_avatar_url`, and `m.3pid_changes` capabilities as per [MSC3283](https://github.com/matrix-org/matrix-doc/pull/3283).

changelogs/client_server/newsfragments/3615.feature

@@ -1 +0,0 @@
-Add support for fallback keys (optional keys used once one-time keys run out), as per [MSC2732](https://github.com/matrix-org/matrix-doc/pull/2732).

changelogs/client_server/newsfragments/3616.feature

@@ -1 +0,0 @@
-Add token-authenticated registration support as per [MSC3231](https://github.com/matrix-org/matrix-doc/pull/3231).

changelogs/client_server/newsfragments/3616.new

@@ -1 +0,0 @@
-Add `/_matrix/client/v1/register/m.login.registration_token/validity` as per [MSC3231](https://github.com/matrix-org/matrix-doc/pull/3231).

changelogs/client_server/newsfragments/3624.breaking

@@ -1 +0,0 @@
-The `aliases` property from the chunks returned by `/publicRooms`, as per [MSC2432](https://github.com/matrix-org/matrix-doc/pull/2432).

changelogs/client_server/newsfragments/3636.clarification

@@ -1 +0,0 @@
-Clarify how to interpret missing one-time key counts.

changelogs/client_server/newsfragments/3650.clarification

@@ -1 +0,0 @@
-Correct the schema for the responses  for various API endpoints.

changelogs/client_server/newsfragments/3652.clarification

@@ -1 +0,0 @@
-Clarify that group mentions are no longer in the specification.

changelogs/client_server/newsfragments/3658.clarification

@@ -1 +0,0 @@
-Distinguish between "federation" event format as exchanged by the Federation API, and the "client" event formats as used in the client-server and AS APIs.

changelogs/client_server/newsfragments/3671.clarification

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

changelogs/client_server/newsfragments/3674.clarification

@@ -1 +0,0 @@
-Fix the rendering of the responses for various API endpoints.

changelogs/client_server/newsfragments/3680.clarification

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

changelogs/header.md

@@ -9,7 +9,7 @@ Variables:
 ## VERSION
 
 <table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/VERSION">https://github.com/matrix-org/matrix-doc/tree/VERSION</a></td>
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/VERSION">https://github.com/matrix-org/matrix-spec/tree/VERSION</a></td>
 <tr><th>Release date</th><td>DATE</td>
 </table>
 

changelogs/identity_service/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/identity_service/newsfragments/1808.clarification

@@ -0,0 +1 @@
+Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).

changelogs/identity_service/newsfragments/3610.feature

@@ -1 +0,0 @@
-Add the `room_type` to stored invites as per [MSC3288](https://github.com/matrix-org/matrix-doc/pull/3288).

changelogs/identity_service/newsfragments/3674.clarification

@@ -1 +0,0 @@
-Fix the rendering of the responses for various API endpoints.

changelogs/internal/newsfragments/1765.clarification

@@ -0,0 +1 @@
+Fix npm release script for `@matrix-org/spec`.

changelogs/internal/newsfragments/1769.clarification

@@ -0,0 +1 @@
+Formatting fixes in CONTRIBUTING.rst.

changelogs/internal/newsfragments/1770.clarification

@@ -0,0 +1 @@
+Reduce whitespace on mobile viewports

changelogs/internal/newsfragments/1771.clarification

@@ -0,0 +1 @@
+Arrange rows in `.basic-info` tables vertically when horizontal space is constrained.

changelogs/internal/newsfragments/1773.clarification

@@ -0,0 +1 @@
+Simplify uses of `resolve-refs` partial.

changelogs/internal/newsfragments/1775.clarification

@@ -0,0 +1 @@
+Fix Hugo warnings.

changelogs/internal/newsfragments/1781.clarification

@@ -0,0 +1 @@
+Fix `github-labels.rst`

changelogs/internal/newsfragments/1786.clarification

@@ -0,0 +1 @@
+Upgrade jsonschema and python-jsonpath CI scripts dependencies.

changelogs/internal/newsfragments/1787.clarification

@@ -0,0 +1 @@
+Solve `allOf` recursively in OpenAPI and JSON Schemas.

changelogs/internal/newsfragments/1788.clarification

@@ -0,0 +1 @@
+Fix Hugo warnings.

changelogs/internal/newsfragments/1789.clarification

@@ -0,0 +1 @@
+Fix property type resolution in `render-object-table` partial.

changelogs/internal/newsfragments/1793.misc

@@ -0,0 +1 @@
+Factor out common definition of `Tag` type.

changelogs/internal/newsfragments/1794.clarification

@@ -0,0 +1 @@
+Update the version of Hugo used to render the spec to v0.124.1.

changelogs/internal/newsfragments/1796.clarification

@@ -0,0 +1 @@
+Add support for pattern formats for `patternProperties`.

changelogs/internal/newsfragments/1797.clarification

@@ -0,0 +1 @@
+Clean up unnecessary `allOf`s in OpenAPI definitions.

changelogs/internal/newsfragments/1798.clarification

@@ -0,0 +1 @@
+Show information about "Additional Properties" in object tables.

changelogs/internal/newsfragments/1799.clarification

@@ -0,0 +1 @@
+Fix anchors for schemas under `oneOf`.

changelogs/internal/newsfragments/1800.clarification

@@ -0,0 +1 @@
+Use reference to `OneTimeKeys` schema in OpenAPI definitions.

changelogs/internal/newsfragments/1801.clarification

@@ -0,0 +1 @@
+Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`.

changelogs/internal/newsfragments/1802.clarification

@@ -0,0 +1 @@
+Add anchors in `definition` shortcode.

changelogs/internal/newsfragments/1803.clarification

@@ -0,0 +1 @@
+Update most CI actions.

changelogs/internal/newsfragments/1804.clarification

@@ -0,0 +1 @@
+Update typos CI action.