Fix unintentional stateres change added in #1042 (#1158)

* Fix unintentional stateres change added in #1042

* Changelog

.github/ISSUE_TEMPLATE/config.yaml

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

.github/ISSUE_TEMPLATE/release.md

@@ -1,37 +0,0 @@
----
-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)):
-
-* [ ] Pin this issue to the repo.
-* [ ] 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.
-* [ ] Unpin this issue from the repo.
-
-Known release blockers:
-* [ ] <!-- Issue/PR link -->

.github/PULL_REQUEST_TEMPLATE/spec-change.md

@@ -1,3 +1,11 @@
+---
+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
 

.github/_typos.toml

@@ -10,4 +10,3 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
-Iy = "Iy"

.github/workflows/checks.yaml

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

@@ -1,9 +1,4 @@
 name: "Spec"
-
-env:
-  HUGO_VERSION: 0.148.1
-  PYTHON_VERSION: 3.13
-
 on:
   push:
     branches:
@@ -23,71 +18,44 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '14'
-      - name: "🔎 Run validator"
+      - name: "⚙️ npm"
+        working-directory: "./scripts"
         run: |
-          npx @redocly/cli@latest lint data/api/*/*.yaml
+          npm install
+      - 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"
 
-  check-event-examples:
+  check-examples:
     name: "🔎 Check Event schema examples"
     runs-on: ubuntu-latest
+    container: uhoreg/matrix-doc-build
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          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
+          /env/bin/python scripts/check-event-schema-examples.py
 
-  check-openapi-examples:
+  check-newsfragments:
-    name: "🔎 Check OpenAPI definitions examples"
+    name: "🔎 Check that new newsfragments are valid"
+    if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - name: "📥 Source checkout"
+      - uses: actions/checkout@v2
-        uses: actions/checkout@v4
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          fetch-depth: 0
-          cache: 'pip'
+      - run: scripts/check-newsfragments
-          cache-dependency-path: scripts/requirements.txt
+        env:
-      - name: "➕ Install dependencies"
+          PULL_REQUEST_NUMBER: ${{ github.event.number }}
-        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: ${{ env.PYTHON_VERSION }}
-          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-json-schemas.py
         
   calculate-baseurl:
     name: "⚙️ Calculate baseURL for later jobs"
@@ -104,127 +72,76 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo "baseURL=/" >> "$GITHUB_OUTPUT"
+              echo ::set-output name=baseURL::/
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
+              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
           else
-              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
+              echo ::set-output name=baseURL::/unstable
           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@v4
+        uses: actions/checkout@v2
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
-          cache-dependency-path: scripts/requirements.txt
-      - name: "➕ Install dependencies"
-        run: |
-          pip install -r scripts/requirements.txt
       - name: "📦 Asset creation"
         run: |
-          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+          python3 -m venv env && . env/bin/activate
-            export RELEASE="${GITHUB_REF/refs\/tags\//}"
+          pip install -r scripts/requirements.txt
-          else
-            export RELEASE="unstable"
-          fi
           # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-openapi.py \
+          scripts/dump-swagger.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-openapi.py \
+          scripts/dump-swagger.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-openapi.py \
+          scripts/dump-swagger.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
-          scripts/dump-openapi.py \
-              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
-              --api identity \
-              -r "$RELEASE" \
-              -o spec/identity-service-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v2
         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: ${{ env.PYTHON_VERSION }}
-      - 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/unstable.md
-
   build-spec:
     name: "📖 Build the spec"
     runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-openapi, generate-changelog]
+    needs: [calculate-baseurl, build-openapi]
-    # run even if generate-changelog was skipped
-    if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '14'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
         with:
-          hugo-version: ${{ env.HUGO_VERSION }}
+          hugo-version: '0.93.3'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
       - 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@v4
+        uses: actions/download-artifact@v2
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -234,39 +151,11 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v2
         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.yml
-
   build-historical-spec:
     name: "📖 Build the historical backup spec"
     runs-on: ubuntu-latest
@@ -274,29 +163,30 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '14'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
         with:
-          hugo-version: ${{ env.HUGO_VERSION }}
+          hugo-version: '0.93.3'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
       - name: "⚙️ npm"
         run: |
           npm i
           npm run get-proposals
       - name: "⚙️ hugo"
-        env:
-          HUGO_PARAMS_VERSION_STATUS: "historical"
         # Create a baseURL like `/v1.2` out of the `v1.2` tag
         run: |
-          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
+          echo -e '[params.version]\nstatus="historical"' > historical.toml
+          hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v2
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -306,7 +196,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v2
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -25,20 +25,17 @@ jobs:
         id: readctx
         # we need to find the PR number that corresponds to the branch, which we do by
         # searching the GH API
-        env:
-          OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }}
-          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
         run: |
-          head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}"
+          head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.head_branch}}'
           echo "head branch: $head_branch"
           pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)"
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
                jq -r '.[] | .number')
           echo "PR number: $pr_number"
-          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
+          echo "::set-output name=prnumber::$pr_number"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
+        uses: dawidd6/action-download-artifact@af92a8455a59214b7b932932f2662fdefbd78126 # v2.15.0
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
@@ -49,7 +46,8 @@ jobs:
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
+        # v1.2.2
+        uses: nwtgck/actions-netlify@f517512ae75beec8896aa7b027c1c72f01816200
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -1,43 +0,0 @@
-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
-    permissions:
-      contents: read
-      id-token: write
-    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"
-
-      # Ensure npm 11.5.1 or later is installed
-      - name: Update npm
-        run: npm install -g npm@latest
-
-      - 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
-        run: npm publish --provenance --access public --tag latest

.github/workflows/spell-check.yaml

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

.gitignore

@@ -2,7 +2,7 @@ node_modules
 /data/msc
 /env*
 /resources
-/scripts/openapi
+/scripts/swagger
 /scripts/tmp
 /hugo-config.toml
 /public
@@ -14,4 +14,3 @@ _rendered.rst
 /spec/
 changelogs/rendered.*
 .hugo_build.lock
-hugo_stats.json

.gitmodules

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

.htmltest.yml

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

CONTRIBUTING.rst

@@ -12,7 +12,7 @@ The documentation style is described at
 https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
 
 Matrix-spec workflows
----------------------
+--------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -72,16 +72,12 @@ ask.
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-All changes to the contents of this repository require a changelog entry. Adding to the changelog can only
+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/twisted/towncrier>`_ in the
-form of "news fragments". Depending on which API you changed, an entry should be added to
+form of "news fragments". The news fragments for the client-server API are stored
-each relevant API's ``newsfragments`` directory. A directory exists for each API under
+under ``changelogs/client_server/newsfragments``.
-``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:
@@ -99,12 +95,13 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``deprecation`` - Used when deprecating something.
 
-* ``removal`` - Used when removing something that was unused or previously deprecated.
-
 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
 --------
 
@@ -119,7 +116,7 @@ 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 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
+`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::
@@ -165,6 +162,7 @@ include the line in your commit or pull request comment::
 
     Signed-off-by: Your Name <your@email.example.org>
 
-Git allows you to add this signoff automatically when using the ``-s``
+...using your real name; unfortunately pseudonyms and anonymous contributions
-flag to ``git commit``, which uses the name and email set in your
+can't be accepted. Git makes this trivial - just use the -s flag when you do
-``user.name`` and ``user.email`` git configs.
+``git commit``, having first set ``user.name`` and ``user.email`` git configs
+(which you should have done anyway :)

README.md

@@ -1,6 +1,6 @@
 # Matrix Specification
 
-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.
+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](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 OpenAPI definitions and schemas are.
+  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.
@@ -52,7 +52,6 @@ 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.
-* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions.
 
 ## Authoring changes to the spec
 
@@ -61,19 +60,20 @@ 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.146.0 is required.
+   v0.93.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 `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
+2. Run `git submodule update --init --recursive` for good measure.
-3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
+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"
    page and is not required.
-4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
+5. 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.
-5. Edit the specification 🙂
+6. 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
@@ -86,13 +86,15 @@ 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 OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+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-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file,
+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:
 
-* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
+* 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/openapi-http-server.py`, and then view the documentation by
+* You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation via an
-  opening `./scripts/openapi-preview.html` in your browser.
+  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.
 
 ## Issue tracking
 

assets/css/fonts/Inter.css

@@ -1,63 +0,0 @@
-/* cyrillic-ext */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-cyrillic-ext-normal.woff2) format('woff2');
-  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
-}
-/* cyrillic */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-cyrillic-normal.woff2) format('woff2');
-  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
-}
-/* greek-ext */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-greek-ext-normal.woff2) format('woff2');
-  unicode-range: U+1F00-1FFF;
-}
-/* greek */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-greek-normal.woff2) format('woff2');
-  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
-}
-/* vietnamese */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-vietnamese-normal.woff2) format('woff2');
-  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
-}
-/* latin-ext */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-latin-ext-normal.woff2) format('woff2');
-  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
-}
-/* latin */
-@font-face {
-  font-family: 'Inter';
-  font-style: normal;
-  font-weight: 100 900;
-  font-display: swap;
-  src: local('Inter'), url(../../fonts/Inter-latin-normal.woff2) format('woff2');
-  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
-}

assets/diagrams/threaded-dag-threads.drawio

@@ -1 +0,0 @@
-<mxfile host="app.diagrams.net" modified="2022-09-27T03:26:23.216Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="YZcXq9Sm_7Lqw5o2RvSU" version="14.6.7" type="device"><diagram id="_rQ0dgHO1UnHExDn0l7E" name="Page-1">7ZpdU+IwFIZ/DZc6bdNWuJQCujPquOvOrl452TbQaNowIXztr9+EJv0goLCirYwyo81JGpL3PQ8nU2mBIFlcMDiOr2mESMuxokUL9FqO41i+I/7IyDKL2JbvZZERw5GKFYE7/BfpgSo6xRGaVAZySgnH42owpGmKQl6JQcbovDpsSEn1XcdwhIzAXQiJGf2NIx5n0bZzVsQvER7F+p1tv5P1JFAPVjuZxDCi81II9FsgYJTy7CpZBIhI9bQu2X2DLb35whhK+S43/PIf6YMfPSfXNzfx1WP3ez/2ToDaxwySqdrxz5ghGInYudQaJ4jgFKkt8KXWhdFpGiE5td0C3XmMObobw1D2zkUqiFjME6K6hzTlA5hgIrPgEpEZ4jiEsgMTElBC2WpS0O/Jl4jPEJMjyDnBo1T0cTpW09ypJajty4FosVURO9dZZCiiCeJsKYbo9NTWqOT0dHteOO2c+acqY+Oyz201FKr8GuWzFxaIC+XCPo742x3pHrsjAFQdcS3TEdu3Nvhhv5sfruHHNcTpsTuRq7zUHJhO5G59jBO2YcS5If0rYsPJOCsSQ7yQBq2LHAR9byDW2D2Egp2qgsDeoOAGAcG76dc25EKRKHaqSRmP6YimkPSLaLeay8WYKyrTbhV8QpwvVeWGU06rkqMF5vfi2lLXD/JafKRmrd6i1NVb6kYq9nuvJ5CN0l2yWdy2aun7Kiz9FHhOxHZv0Fz8/kETmObGyn2/bKuQiU5ZiF7QUx1tOGQjxF/LWzNNGCKQ41l1HQc33TGg6TYZGsdvGDQueDM0T9NkrMenNEU1cFRC56GM1RaOCPyDSBeGz6PVTkpeDwL5eqlsHRAw8BkAAwZgwZsBOwRIbn5u1afbjlczSs4XSnWh5O6IklMnSuZJu9cElMBaTXLdumuSewwg7Xm2awhI3o4ggTpB8gyQ+o0AyW5eTbINYb5Q+iCU/B1RcutEyXwaN2gCSu76g7K6axLoGEIlpwzBkGOaHgNje577IjiJ8+XLxi3kHLF0FXEstzkYnr2toqmEPLFObfFTSUpbfbjvTKqa/ZZisYliCB0OJ2Jp6ymaL+L/s9b878dFE+g2C6Xv1lwoQXsD3yjC/BjY3rN+fh62Ozuy7dVZYs3KcdkECF3QvNOqZQhz/LQ1BCX9ILrZj1D0KkswfWsETO6HPdcXzeJLFdlBofhuCuj/Aw==</diagram></mxfile>

assets/diagrams/threaded-dag.drawio

@@ -1 +0,0 @@
-<mxfile host="app.diagrams.net" modified="2022-09-27T03:11:43.523Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="L_ujIRop4Jndk67DcTE9" version="14.6.7" type="device"><diagram id="_rQ0dgHO1UnHExDn0l7E" name="Page-1">7VpbU+IwFP41PMqkTS/wKDfdGXXcdWdXn5wsDTTaNkwIAvvrN6UJbYlCF1gbXcYZTU5P0ub0u6S1DdiNFxcMTcJrGuCoYYNg0YC9hm3bwLPFnzSyzCIW8NwsMmYkkLE8cEd+Y5UoozMS4GkpkVMacTIpB4c0SfCQl2KIMTovp41oVD7rBI2xFrgbokiP/iQBD7Noy/bz+CUm41Cd2fLa2ZEYqWS5kmmIAjovhGC/AbuMUp614kUXR2n1VF2ycYM3jq4vjOGEVxnww3ukD17wHF/f3IRXj52v/dA9k7O8oGgmF3wur5YvVQnmIeH4boKGaX8u7nMDdkIeR6JniSaaTrLCj8gCi3N15JSYcbx481qtdQUEdjCNMWdLkaIGQFk0BRtH9uf5PVApYaH8KobkXR+vZ84LIxqyNn9Tp5ZWFhwIoMguZTykY5qgqJ9HO4zOkiAtyapOec4VpRMZfMKcLyXq0YzTcmnxgvB70Qay/ZC2m67s9RaFQ72l6iRivfdqgrRTGJV282Grnho3ogkfoJhEaeA7iQXpbHCD5+L3NxqjZH1j03Vvv62iTHTGhnhLPaUscMTGmO/Cpw4ThiPEyUv5Oo5+022NHB0TyGED08jhn8hxTHLAiuSwayWHr7EjbvKQYRQcjIanWTxR+QlN8IEAadpuASNWNYSApu8WQWLtgEiApuF6AWnnFnGOWbKK2MAR0Qj9wlEHDZ/Hq+V2aUTZqkBw0E1/NoF2iaMXzMkQ1QOvWrUXaujqGqG9vmna2z5p7zHJ4VQkB6xVe52Po71F6QXVALIpvWAHQj6O9FZFV63OroOrZ4L0Qsc06XVP0ntMcrgVyeHUKr3ux5He/ba99ifd9laF13YVOgNNB/pSIitDbjXdOWNoWUiYUJLwaeFst2kgP5WjZpSCp577B2/kW7C1LV80sivYGK0uh45GU1GYTYKsS7A/Z3TK9E0wFMeCTdcwS3FOlnJMznsVOe/Wain6e0ZjLWWv3bz9SXfzVdF16G5+L/dwwYa27XAPG7S25Zfd41jO4GnIHxjhDG3THjXgyReOyVy/InO9Wn1BZ0fcFK4w5IQmRjvDf/+KvSq+Dn2LuJ8ztMrOoH04sOkMbbgt/984g/7fpQsTnME17v2/fZASgJMzlOvZrshcv1ZnAK84Aw4If7ddwrvq/puKXcEQpkIeSDL+vloMyAOi54LXbbCA8wp2UgP2an1abWvQuzRBmD3XNGG2tLKchPkAcqgPQneyo10nOyxdmb+YQA///T6oFN38o9ZsO5h/Gwz7fwA=</diagram></mxfile>

assets/icons/favicon.svg

@@ -1,12 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
-   <style>
-      path { fill: #000000; }
-      @media (prefers-color-scheme: dark) {
-          path { fill: #ffffff; }
-      }
-   </style>
-   <path d="M 30,2.0000001 V 30 h -1 -2 v 2 h 5 V -3.3333334e-8 L 27,0 v 2 z"/>
-   <path d="M 9.9515939,10.594002 V 12.138 h 0.043994 c 0.3845141,-0.563728 0.8932271,-1.031728 1.4869981,-1.368 0.580003,-0.322998 1.244999,-0.485 1.993002,-0.485 0.72,0 1.376999,0.139993 1.971998,0.42 0.595,0.279004 1.047001,0.771001 1.355002,1.477001 0.338003,-0.500001 0.795999,-0.941 1.376999,-1.323001 0.579999,-0.382998 1.265998,-0.574 2.059998,-0.574 0.602003,0 1.160002,0.074 1.674002,0.220006 0.514,0.148006 0.953998,0.382998 1.321999,0.706998 0.36601,0.322999 0.653001,0.746 0.859,1.268002 0.205001,0.521998 0.307994,1.15 0.307994,1.887001 v 7.632997 h -3.127 v -6.463997 c 0,-0.383002 -0.01512,-0.743002 -0.04399,-1.082003 -0.02079,-0.3072 -0.103219,-0.607113 -0.242003,-0.881998 -0.133153,-0.25081 -0.335962,-0.457777 -0.584001,-0.596002 -0.257008,-0.146003 -0.605998,-0.220006 -1.046997,-0.220006 -0.440002,0 -0.796003,0.085 -1.068,0.253002 -0.272013,0.170003 -0.485001,0.390002 -0.639001,0.662003 -0.159119,0.287282 -0.263585,0.601602 -0.307994,0.926997 -0.05197,0.346923 -0.07801,0.697217 -0.07801,1.048002 v 6.353999 h -3.128005 v -6.398 c 0,-0.338003 -0.0072,-0.673001 -0.02116,-1.004001 -0.01134,-0.313663 -0.07487,-0.623229 -0.187994,-0.915999 -0.107943,-0.276623 -0.300435,-0.512126 -0.550001,-0.673001 -0.25799,-0.168 -0.636,-0.253002 -1.134999,-0.253002 -0.198123,0.0083 -0.394383,0.04195 -0.584002,0.100006 -0.258368,0.07446 -0.498455,0.201827 -0.704999,0.373985 -0.227981,0.183987 -0.421999,0.449 -0.583997,0.794003 -0.161008,0.345978 -0.242003,0.797998 -0.242003,1.356998 v 6.618999 H 6.99942 V 10.590001 Z"/>
-   <path d="M 2,2.0000001 V 30 h 3 v 2 H 0 V 9.2650922e-8 L 5,0 v 2 z"/>
-</svg>

assets/js/toc.js

@@ -1,169 +0,0 @@
-/*
-Copyright 2020, 2021 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/*
-  Only call the given function once every 250 milliseconds to avoid impacting
-  the performance of the browser.
-  Source: https://remysharp.com/2010/07/21/throttling-function-calls
-*/
-function throttle(fn) {
-  const threshold = 250;
-  let last = null;
-  let deferTimer = null;
-
-  return function (...args) {
-    const now = new Date();
-
-    if (last && now < last + threshold) {
-      // Hold on to it.
-      clearTimeout(deferTimer);
-      deferTimer = setTimeout(() => {
-        last = now;
-        fn.apply(this, args);
-      }, threshold);
-    } else {
-      last = now;
-      fn.apply(this, args);
-    }
-  }
-}
-
-/*
-  Get the list of headings that appear in the ToC.
-  This is not as simple as querying all the headings in the content, because
-  some headings are not rendered in the ToC (e.g. in the endpoint definitions).
-*/
-function getHeadings() {
-  let headings = [];
-
-  // First get the anchors in the ToC.
-  const toc_anchors = document.querySelectorAll("#toc nav a");
-
-  for (const anchor of toc_anchors) {
-    // Then get the heading from its selector in the anchor's href.
-    const selector = anchor.getAttribute("href");
-    if (!selector) {
-      console.error("Got ToC anchor without href");
-      continue;
-    }
-    
-    const heading = document.querySelector(selector);
-    if (!heading) {
-      console.error("Heading not found for selector:", selector);
-      continue;
-    }
-
-    headings.push(heading);
-  }
-
-  return headings;
-}
-
-/*
-  Get the heading of the text visible at the top of the viewport.
-  This is the first heading above or at the top of the viewport.
-*/
-function getCurrentHeading(headings, headerOffset) {
-  const scrollTop = document.documentElement.scrollTop;
-  let prevHeading = null;
-  let currentHeading = null;
-  let index = 0;
-
-  for (const heading of headings) {
-    // Compute the position compared to the viewport.
-    const rect = heading.getBoundingClientRect();
-
-    if (rect.top >= headerOffset && rect.top <= headerOffset + 30) {
-      // This heading is at the top of the viewport, this is the current heading.
-      currentHeading = heading;
-      break;
-    }
-    if (rect.top >= headerOffset) {
-      // This is in or below the viewport, the current heading should be the
-      // previous one.
-      if (prevHeading) {
-        currentHeading = prevHeading;
-      } else {
-        // The first heading does not have a prevHeading.
-        currentHeading = heading;
-      }
-      break;
-    }
-
-    prevHeading = heading;
-    index += 1;
-  }
-
-  // At the bottom of the page we might not have a heading.
-  if (!currentHeading) {
-    currentHeading = prevHeading;
-  }
-
-  return currentHeading;
-}
-
-/*
-  Select the ToC entry that points to the given ID.
-  Clear any previously highlighted ToC items, select the new one,
-  and adjust the ToC scroll position.
-*/
-function selectTocEntry(id) {
-  // Deselect previously selected entries.
-  const activeEntries = document.querySelectorAll("#toc nav a.active");
-  for (const activeEntry of activeEntries) {
-    activeEntry.classList.remove('active');
-  }
-
-  // Find the new entry and select it.
-  const newEntry = document.querySelector(`#toc nav a[href="#${id}"]`);
-  if (!newEntry) {
-    console.error("ToC entry not found for ID:", id);
-    return;
-  }
-  newEntry.classList.add('active');
-
-  // Don't scroll the sidebar nav if the main content is not scrolled
-  const nav = document.querySelector("#td-section-nav");
-  const content = document.querySelector("html");
-  if (content.scrollTop !== 0) {
-    nav.scrollTop = newEntry.offsetTop - 100;
-  } else {
-    nav.scrollTop = 0;
-  }
-}
-
-/*
-  Track when the view is scrolled, and use this to update the highlight for the
-  corresponding ToC entry.
-*/
-window.addEventListener('DOMContentLoaded', () => {
-  // Part of the viewport is below the header so we should take it into account.
-  const headerOffset = document.querySelector("body > header > nav").clientHeight;
-  const headings = getHeadings();
-
-  const onScroll = throttle((_e) => {
-    // Update the ToC.
-    let heading = getCurrentHeading(headings, headerOffset);
-    selectTocEntry(heading.id);
-  });
-
-  // Initialize the state of the ToC.
-  onScroll();
-
-  // Listen to scroll and resizing changes.
-  document.addEventListener('scroll', onScroll, false);
-  document.addEventListener('resize', onScroll, false);
-});

assets/js/versions.template.js

@@ -1,114 +0,0 @@
-/*
-Copyright 2025 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-// Determine the current version as defined in hugo.toml. This will either be
-// "unstable" or "vX.X" and doesn't depend on the current URL.
-//
-// The oddity below is an attempt at producing a readable Hugo template while
-// avoiding JS syntax errors in your IDE.
-const currentVersion = `{{ if eq .Site.Params.version.status "unstable" }}
-    {{- /**/ -}}
-    unstable
-    {{- /**/ -}}
-{{ else }}
-    {{- /**/ -}}
-    {{ printf "v%s.%s" .Site.Params.version.major .Site.Params.version.minor }}
-    {{- /**/ -}}
-{{ end }}`;
-
-// Determine the current version segment by regex matching the URL. This will either
-// be "unstable", "latest", "vX.X" (production) or undefined (local & netlify).
-const href = window.location.href;
-const segmentMatches = href.match(/(?<=\/)unstable|latest|v\d+.\d+(?=\/)/);
-const currentSegment = segmentMatches ? segmentMatches[0] : undefined;
-
-// Determine the selected menu element. If we were able to obtain the version
-// segment from the URL (production), use that. Otherwise (local & netlify),
-// fall back to the version as defined in Hugo.
-const selected = currentSegment ?? currentVersion;
-
-function appendVersion(parent, name, segment, url) {
-    // The list item
-    const li = document.createElement("li");
-    if (segment === selected) {
-        li.classList.add("version-picker-selected");
-    }
-    if (segment === "latest") {
-        li.classList.add("version-picker-latest");
-    }
-    parent.appendChild(li);
-
-    // The link
-    const a = document.createElement("a");
-    a.classList.add("dropdown-item");
-    a.setAttribute("href", url);
-    li.appendChild(a);
-
-    // Handle clicks manually to preserve the current path / fragment
-    a.addEventListener("click", (ev) => {
-        // If the URL is a relative link (i.e. the historical versions changelog), just
-        // let the browser load it
-        if (url.startsWith("/")) {
-            return;
-        }
-
-        // If we couldn't determine the current segment, we cannot safely replace
-        // it and have to let the browser load the (root) URL instead
-        if (!currentSegment) {
-            return;
-        }
-
-        // Otherwise, stop further event handling and replace the segment
-        ev.preventDefault();
-        ev.stopPropagation();
-        window.location.href = href.replace(`/${currentSegment}/`, `/${segment}/`);
-    });
-
-    // The link text
-    const text = document.createTextNode(name);
-    a.appendChild(text);
-}
-
-// If we're in the unstable version, we're the latest thing and can just load
-// versions.json from our own resources. Otherwise, we fall back to loading it
-// from /unstable/versions.json, assuming we are on the spec.matrix.org deployment.
-const url = currentVersion === "unstable"
-    ? '{{ .Site.Home.Permalink }}versions.json'
-    : "/unstable/versions.json";
-
-fetch(url)
-    .then(r => r.json())
-    .then(versions => {
-        // Find the surrounding list element
-        const ul = document.querySelector("ul#version-selector");
-        if (!ul) {
-            console.error("Cannot populate version selector: ul element not found");
-            return;
-        }
-
-        // Add a entries for the unstable version and the "latest" shortcut
-        appendVersion(ul, "unstable", "unstable", "https://spec.matrix.org/unstable");
-        const latestName = versions?.length ? `latest (${versions[0].name})` : "latest";
-        appendVersion(ul, latestName, "latest", "https://spec.matrix.org/latest");
-
-        // Add an entry for each proper version
-        for (const version of versions) {
-            appendVersion(ul, version.name, version.name, `https://spec.matrix.org/${version.name}`);
-        }
-
-        // For historical versions, simply link to the changelog
-        appendVersion(ul, "historical", "historical", '{{ (site.GetPage "changelog/historical").RelPermalink }}');
-    });

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,27 +30,12 @@ $note: $secondary;
 $note-background: $secondary-background;
 $warning-background: #FFE0E0;
 
-// colours for definition tables.
+$table-row-alternate: $secondary-lightest-background;
-// the border colour matches that used for "highlight" divs
+$table-row-default: $secondary-lighter-background;
-$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;
 
 /*
- * The $font-family-sans-serif definition here overrides the default value set by docsy
+ Opt to serve fonts locally by overriding web-font-path to be a non-google fonts URL.
- * (https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68)
+ This is only possible with our modified docsy theme: https://github.com/matrix-org/docsy
  */
-$font-family-sans-serif:
+$web-font-path: "../css/fonts/Inter.css";
-  // Add "Inter" to the front, making it the default. The font itself is loaded via stylesheet
+$google_font_name: "Inter";
-  // links in layouts/partials/hooks/head-end.html.
-  "Inter",
-  -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
-  // Insert fonts suited for mathematical symbols on different platforms before "Arial"
-  "STIX Two Math", "Cambria Math", "Noto Sans Math", "Dejavu Sans",
-  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/custom.scss

@@ -18,6 +18,9 @@ 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:
@@ -34,36 +37,15 @@ 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 {
     color: $black;
   }
-
-  /* Make the version dropdown scroll if it's too large */
-  ul#version-selector {
-    max-height: 80vh;
-    overflow-y: auto;
-  }
-
-  ul#version-selector li.version-picker-selected a {
-    font-weight: bold;
-  }
-
-  ul#version-selector li.version-picker-latest a {
-    color: $secondary;
-  }
 }
 
 /* Styles for the sidebar nav */
@@ -80,8 +62,9 @@ Custom SCSS for the Matrix spec
     margin-top: 1rem;
   }
 
-  .td-sidebar-nav__section .ul-1 ul {
+  &>.td-sidebar-nav__section > li > a.td-sidebar-link {
-    padding-left: 0;
+      font-weight: $font-weight-bold;
+      font-size: 1.3rem;
   }
 
   /* This is to make the width of the items that have sub-items (like room versions)
@@ -90,20 +73,12 @@ Custom SCSS for the Matrix spec
     padding-right: 0 !important;
   }
 
-  .ul-1 > li > a {
+  a.indent-1 {
     padding-left: 1rem !important;
   }
 
-  .ul-2 > li > a {
+  a.indent-2 {
-    padding-left: 2rem !important;
+    padding-left: 2rem;
-  }
-
-  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 {
@@ -122,11 +97,12 @@ Custom SCSS for the Matrix spec
 
     &.active, &active:hover {
       background-color: $secondary-background;
+      font-weight: $font-weight-normal;
     }
   }
 }
 
-@include media-breakpoint-up(md) {
+@media (min-width: 768px) {
   @supports (position: sticky) {
     .td-sidebar-nav {
       /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
@@ -136,11 +112,8 @@ Custom SCSS for the Matrix spec
 }
 
 /* Customise footer */
-.td-footer {
+footer {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
-  padding-top: 2rem;
-  color: var(--bs-body-color);
-  background-color: var(--bs-body-color-bg);
 }
 
 /* Auto numbering for headings */
@@ -186,19 +159,18 @@ Custom SCSS for the Matrix spec
 
 }
 
-/* Remove some padding before the main content, when the sidebar is disabled */
+/* Adjust heading anchors for site header */
-.td-main main {
+.td-content {
-  @include media-breakpoint-down(md) {
+  &> h2,
-    padding-top: 0;
+  &> h3,
+  &> h4,
+  &> h5,
+  &> h6,
+  .rendered-data h1 {
+    scroll-margin-top: 5rem;
   }
 }
 
-/* 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;
@@ -257,69 +229,6 @@ Custom SCSS for the Matrix spec
 
 }
 
-.endpoints-toc {
-  summary {
-    cursor: pointer;
-    font-weight: $font-weight-bold;
-    font-size: 1.05rem;
-    margin-bottom: 0.5rem;
-  }
-
-  .endpoint-list {
-    list-style: none;
-    padding-left: 0;
-    margin: 0;
-  }
-
-  .endpoint-list li {
-    margin: 0.2rem 0;
-  }
-
-  .endpoint-list a {
-    text-decoration: none;
-    color: inherit;
-    padding: 0.05rem 0.25rem;
-    border-radius: 0.2rem;
-
-    &:hover {
-      background-color: $secondary-background;
-    }
-  }
-
-  .endpoint-list .http-api-method {
-    margin-right: 0.35rem;
-    font-weight: $font-weight-bold;
-  }
-
-  .endpoint-path {
-    font-family: $font-family-monospace;
-    color: $secondary;
-  }
-
-  .endpoint-deprecated {
-    color: $danger;
-    font-weight: $font-weight-bold;
-    margin-left: 0.35rem;
-  }
-
-  .endpoint-module {
-    &:not(:first-child) {
-      margin-top: 0.75rem;
-    }
-  }
-
-  .endpoint-module-title {
-    // font-weight: $font-weight-bold;
-    font-size: 1.20rem;
-    margin-bottom: 0.35rem;
-  }
-}
-
-.page-description {
-  margin-bottom: 1rem;
-  color: inherit;
-}
-
 /* Styles for alert boxes */
 .alert {
   &.note {
@@ -354,22 +263,18 @@ Custom SCSS for the Matrix spec
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
-.td-content .rendered-data {
+.rendered-data {
-  background-color: $secondary-lightest-background;
+  margin: 1rem 0 3rem 0;
-  padding: 0.85rem;
-  margin: 0.85rem 0;
 
   details {
     summary {
-      h1 {
+      padding: .5rem 0;
-        margin: 0;
+      list-style-position: outside;
-        /* Ensure the disclosure control is vertically centred with the header text. */
+
-        vertical-align: middle;
+      p {
+        max-width: 80%;
       }
     }
-    p {
-      max-width: 80%;
-    }
   }
 
   .deprecated-inline {
@@ -393,19 +298,17 @@ Custom SCSS for the Matrix spec
   h2 {
     font-weight: $font-weight-bold;
     font-size: 1.3rem;
-    margin: 1.5rem 0 1rem 0;
+    margin: 3rem 0 .5rem 0;
   }
 
   h3 {
     font-weight: $font-weight-bold;
     font-size: 1.1rem;
-    margin: 1.5rem 0 1rem 0;
+    margin: 1.5rem 0 .75rem 0;
-
   }
 
-  /* Reduce top margin of h3 if previous sibling is a h2 */
+  h2 + table, h3 + table, h3 + div.highlight {
-  h2 + h3 {
+    margin-top: 0;
-    margin-top: 1rem;
   }
 
   hr {
@@ -414,41 +317,13 @@ Custom SCSS for the Matrix spec
   }
 
   p code, table code {
-    background-color: transparent;
+    background-color: $white;
   }
 
   table {
-    @media (max-width: 800px) {
+    table-layout: fixed;
-      /* Docsy by default applies `overflow-x: auto;` to tables, which
+    width: 100%;
-       * results in annoying horizontal scrolling on mobile, so we instead
+    margin: 4rem 0;
-       * 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%;
-      }
-    }
 
     caption {
       caption-side: top;
@@ -459,77 +334,42 @@ Custom SCSS for the Matrix spec
 
     th, td, caption {
       padding: 1rem;
-      border-top: 1px $table-border-color solid;
     }
 
-    td > p:last-child {
+    th {
-      // Avoid unnecessary space at the bottom of the cells.
+      background-color: $white;
-      margin-bottom: 0;
     }
 
-    &.object-table, &.response-table, &.content-type-table {
+    caption, tr {
-        border: 1px $table-border-color solid;
+      background-color: $table-row-default;
+    }
 
-        caption {
+    tr:nth-child(even) {
-            // the caption is outside the table's border box,
+      background-color: $table-row-alternate;
-            // so we have to give it its own border.
-            border: 1px $table-border-color solid;
-
-            // ... 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;
     }
 
-    /* Arrange rows vertically when horizontal space is constrained to avoid overflowing */
+    .col-name, .col-type, .col-status {
-    @include media-breakpoint-down(sm) {
+      width: 25%;
-      /* Make cells full width without vertical margin */
-      &.basic-info th, &.basic-info td {
-        width: 100%;
-        display: inline-block;
-        margin-top: 0;
-        margin-bottom: 0;
-      }
-
-      /* 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;
-      }
-
-      /* Remove top border on all but the first header cell to prevent double borders between rows */
-      &.basic-info tr + tr th {
-        border-top: none;
-      }
     }
-  }
 
-  /* Have consistent spacing around tables and examples */
+    .col-description {
-  table, .highlight {
+      width: 50%;
-    margin-top: 0;
-    margin-bottom: 2rem;
-
-    /* We don't need the margin on the last child of the .rendered-data block */
-    &:last-child {
-      margin-bottom: 0;
     }
+
+    .col-status-description {
+      width: 75%;
+    }
+
   }
 
   pre {
@@ -574,25 +414,12 @@ 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 {
-  @include media-breakpoint-up(md) {
+  padding-right: 3rem;
-    padding-right: 3rem;
-  }
-}
-
-/* Adjust the width of math to match normal paragraphs */
-@include media-breakpoint-up(lg) {
-  .katex-display {
-    max-width: 80%;
-  }
 }
 
 /* Adjust default styles for info banner */
 .pageinfo-primary {
-  @include media-breakpoint-up(lg) {
+  max-width: 80%;
-    max-width: 80%;
-  }
-  margin-top: 0;
-  margin-right: 0;
   margin-left: 0;
   border: 0;
   border-left: solid 5px $secondary;
@@ -606,42 +433,8 @@ Make padding symmetrical (this selector is used in the default styles to apply p
   padding-left: 100px;
 }
 
-/* Adjust the styling of definition lists. */
+/* Full-width tables */
-
+.td-content > table {
-/* Add a little spacing between the term and its definition. */
+  width: 100%;
-dt {
+  display: table;
-   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;
-  }
 }

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
+A description of how email addresses, mobile phone numbers and other third
-identifiers can be used to authenticate and discover users in Matrix.
+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/application_service/newsfragments/1094.feature

@@ -0,0 +1 @@
+Add timestamp massaging as per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316).

changelogs/client_server/newsfragments/1002.feature

@@ -0,0 +1 @@
+Make `from` optional on `GET /_matrix/client/v3/messages` to allow requesting events from the start or end of the room history, as per [MSC3567](https://github.com/matrix-org/matrix-spec-proposals/pull/3567).

changelogs/client_server/newsfragments/1003.clarification

@@ -0,0 +1 @@
+Adjust the OpenAPI specification so that the type `Flow information` is explicitly defined when the client-server API is rendered.

changelogs/client_server/newsfragments/1021.clarification

@@ -0,0 +1 @@
+Correct the default value for `invite` where it is not specified in an `m.room.power_levels` event.

changelogs/client_server/newsfragments/1032.clarification

@@ -0,0 +1 @@
+Update various links which pointed to the old `matrix-doc` github repository.

changelogs/client_server/newsfragments/1035.clarification

@@ -0,0 +1 @@
+Removed `m.room.message.feedback` per [MSC3582](https://github.com/matrix-org/matrix-spec-proposals/pull/3582).

changelogs/client_server/newsfragments/1051.clarification

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

changelogs/client_server/newsfragments/1054.clarification

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

changelogs/client_server/newsfragments/1056.feature

@@ -0,0 +1 @@
+Add refresh tokens, per [MSC2918](https://github.com/matrix-org/matrix-spec-proposals/pull/2918).

changelogs/client_server/newsfragments/1059.clarification

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

changelogs/client_server/newsfragments/1062.feature.1

@@ -0,0 +1 @@
+Relax the restrictions on Rich Replies, as per [MSC3676](https://github.com/matrix-org/matrix-spec-proposals/pull/3676).

changelogs/client_server/newsfragments/1062.feature.2

@@ -0,0 +1 @@
+Describe a structured system for event relationships, as per [MSC2674](https://github.com/matrix-org/matrix-spec-proposals/pull/2674).

changelogs/client_server/newsfragments/1062.feature.3

@@ -0,0 +1 @@
+Describe how relationships between events can be "aggregated", as per [MSC2675](https://github.com/matrix-org/matrix-spec-proposals/pull/2675) and [MSC3666](https://github.com/matrix-org/matrix-spec-proposals/pull/3666).

changelogs/client_server/newsfragments/1081.clarification

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

changelogs/client_server/newsfragments/1097.clarification

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

changelogs/client_server/newsfragments/1099.feature

@@ -0,0 +1 @@
+Add support for a new `knock_restricted` join rule in supported room versions, as per [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787).

changelogs/client_server/newsfragments/1100.clarification

@@ -0,0 +1 @@
+Clarify that state keys starting with `@` are in fact reserved. Regressed from [#3658](https://github.com/matrix-org/matrix-spec-proposals/pull/3658).

changelogs/client_server/newsfragments/1101.deprecation

@@ -0,0 +1 @@
+Deprecate the `sender_key` and `device_id` on `m.megolm.v1.aes-sha2` events, and the `sender_key` on `m.room_key_request` to-device messages, as per [MSC3700](https://github.com/matrix-org/matrix-spec-proposals/pull/3700).

changelogs/client_server/newsfragments/1110.clarification

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

changelogs/client_server/newsfragments/1113.feature

@@ -0,0 +1 @@
+Add refresh tokens, per [MSC2918](https://github.com/matrix-org/matrix-spec-proposals/pull/2918).

changelogs/client_server/newsfragments/1115.clarification

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

changelogs/client_server/newsfragments/1126.clarification

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

changelogs/client_server/newsfragments/1127.clarification

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

changelogs/client_server/newsfragments/1128.clarification

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

changelogs/client_server/newsfragments/1129.clarification

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

changelogs/client_server/newsfragments/3669.clarification

@@ -0,0 +1 @@
+Remove unenforced size limit on the `name` field of `m.room.name` events.

changelogs/client_server/newsfragments/3679.clarification

@@ -0,0 +1 @@
+Remove erroneous `room_id` field from examples of `m.read`, `m.typing` in `/sync` and `m.fully_read` in room account data.

changelogs/client_server/newsfragments/3681.clarification

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

changelogs/client_server/newsfragments/3690.clarification

@@ -0,0 +1 @@
+Clarify the behaviour of `event_match` in push rule conditions.

changelogs/client_server/newsfragments/3708.clarification

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

changelogs/client_server/newsfragments/3711.clarification

@@ -0,0 +1 @@
+Fix incorrectly referenced `m.login.appservice` login identifier, instead using `m.login.application_service`.

changelogs/client_server/newsfragments/3730.clarification

@@ -0,0 +1 @@
+Fix membership state transitions to denote that `invite->knock` and `external->leave` are valid transitions.

changelogs/client_server/newsfragments/987.clarification

@@ -0,0 +1 @@
+Clarify that the url field in `m.room.avatar` events is not required.

changelogs/client_server/newsfragments/989.clarification

@@ -0,0 +1 @@
+Clarify that the `type` in user-interactive authentication can be omitted.

changelogs/header.md

@@ -0,0 +1,16 @@
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    VERSION  = Replaced by the version number (eg: v1.2)
+    DATE     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## VERSION
+
+<table class="release-info">
+<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>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

changelogs/internal/newsfragments/2282.clarification

@@ -1 +0,0 @@
-Replace the Twitter link in the footer with our BlueSky and Mastodon socials.

changelogs/legacy/application_service.rst

@@ -22,5 +22,5 @@ r0.1.0
 
 This is the first release of the Application Service specification. It
 includes support for application services being able to interact with
-homeservers and bridge third-party networks, such as IRC, over to Matrix
+homeservers and bridge third party networks, such as IRC, over to Matrix
 in a standard and accessible way.

changelogs/legacy/client_server.rst

@@ -211,7 +211,7 @@ Backwards Compatible Changes
 - Add a common standard for user, room, and group mentions in messages. (`#1547 <https://github.com/matrix-org/matrix-doc/issues/1547>`_)
 - Add server ACLs as an option for controlling federation in a room. (`#1550 <https://github.com/matrix-org/matrix-doc/issues/1550>`_)
 - Add new push rules for encrypted events and ``@room`` notifications. (`#1551 <https://github.com/matrix-org/matrix-doc/issues/1551>`_)
-- Add third-party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
+- Add third party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
 - Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``. (`#1567 <https://github.com/matrix-org/matrix-doc/issues/1567>`_)
 - Add an ``inhibit_login`` registration option. (`#1589 <https://github.com/matrix-org/matrix-doc/issues/1589>`_)
 - Recommend that servers set a Content Security Policy for the content repository. (`#1600 <https://github.com/matrix-org/matrix-doc/issues/1600>`_)
@@ -554,7 +554,7 @@ Since the draft stage, the following major changes have been made:
   - Push notification
   - History visibility
   - Search
-  - Invites based on third-party identifiers
+  - Invites based on third party identifiers
   - Room tagging
   - Guest access
   - Client config

changelogs/legacy/identity_service.rst

@@ -48,7 +48,7 @@ r0.1.0
 ======
 
 This is the first release of the Identity Service API. With this API, clients and
-homeservers can store bindings between third-party identifiers such as email addresses
+homeservers can store bindings between third party identifiers such as email addresses
 and phone numbers, associating them with Matrix user IDs. Additionally, identity
-servers offer the ability to invite third-party users to Matrix rooms by storing
+servers offer the ability to invite third party users to Matrix rooms by storing
 the invite until the identifier is bound.

changelogs/pyproject.toml

@@ -1,66 +1,39 @@
 [tool.towncrier]
     version = "unused"
-    filename = "rendered.md"
+    filename = "../rendered.md"
-    template = "template.md.jinja"
+    issue_format = "[#{issue}](https://github.com/matrix-org/matrix-spec/issues/{issue})"
+    title_format = "### {name}"  # Matches rendered spec, even if awkward
+    underlines = "   "  # 3 spaces intentionally to hide RST headings
+
+    # Note: The names below have the <strong> tag built-in so the rendered spec *and* the generated
+    # changelog can benefit from sane headings.
 
     [[tool.towncrier.type]]
         directory = "breaking"
-        name = "Breaking Changes"
+        name = "<strong>Breaking Changes</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "deprecation"
-        name = "Deprecations"
+        name = "<strong>Deprecations</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "new"
-        name = "New Endpoints"
+        name = "<strong>New Endpoints</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "removal"
-        name = "Removed Endpoints"
+        name = "<strong>Removed Endpoints</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "feature"
-        name = "Backwards Compatible Changes"
+        name = "<strong>Backwards Compatible Changes</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "clarification"
-        name = "Spec Clarifications"
+        name = "<strong>Spec Clarifications</strong>"
         showcontent = true
-
-    [[tool.towncrier.section]]
-        name = "Client-Server API"
-        path = "client_server"
-
-    [[tool.towncrier.section]]
-        name = "Server-Server API"
-        path = "server_server"
-    
-    [[tool.towncrier.section]]
-        name = "Application Service API"
-        path = "application_service"
-
-    [[tool.towncrier.section]]
-        name = "Identity Service API"
-        path = "identity_service"
-    
-    [[tool.towncrier.section]]
-        name = "Push Gateway API"
-        path = "push_gateway"
-    
-    [[tool.towncrier.section]]
-        name = "Room Versions"
-        path = "room_versions"
-    
-    [[tool.towncrier.section]]
-        name = "Appendices"
-        path = "appendices"
-
-    [[tool.towncrier.section]]
-        name = "Internal Changes/Tooling"
-        path = "internal"

changelogs/room_versions/newsfragments/1037.clarification

@@ -0,0 +1 @@
+Improve readability and understanding of the state resolution algorithms.

changelogs/room_versions/newsfragments/1042.clarification

@@ -0,0 +1 @@
+Improve readability and understanding of the state resolution algorithms.

changelogs/room_versions/newsfragments/1043.clarification

@@ -0,0 +1 @@
+Improve readability and understanding of the state resolution algorithms.

changelogs/room_versions/newsfragments/1050.clarification

@@ -0,0 +1 @@
+Improve readability of the authorization rules.

changelogs/room_versions/newsfragments/1093.clarification

@@ -0,0 +1 @@
+For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event.

changelogs/room_versions/newsfragments/1099.clarification

@@ -0,0 +1 @@
+Clarify that room versions 1 through 9 accept stringy power levels, as noted by [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667).

changelogs/room_versions/newsfragments/1099.feature.1

@@ -0,0 +1 @@
+Add room version 10 as per [MSC3604](https://github.com/matrix-org/matrix-spec-proposals/pull/3604).

changelogs/room_versions/newsfragments/1099.feature.2

@@ -0,0 +1 @@
+Enforce integer power levels in room version 10 as per [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667).

changelogs/room_versions/newsfragments/1099.feature.3

@@ -0,0 +1 @@
+Add a `knock_restricted` join rule supported by room version 10 as per [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787).

changelogs/room_versions/newsfragments/1103.clarification

@@ -0,0 +1 @@
+For all room versions: Add `m.federate` to the authorization rules, as originally intended.

changelogs/room_versions/newsfragments/1107.clarification

@@ -0,0 +1 @@
+For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events.

changelogs/room_versions/newsfragments/1120.clarification

@@ -0,0 +1 @@
+Improve readability and understanding of the state resolution algorithms.

changelogs/room_versions/newsfragments/1158.clarification

@@ -0,0 +1 @@
+For room versions 2–10: correct a mistaken clarification to the state resolution algorithm.

changelogs/room_versions/newsfragments/3737.clarification

@@ -0,0 +1 @@
+For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`.

changelogs/room_versions/newsfragments/3739.feature

@@ -0,0 +1 @@
+Update the default room version to 9 as per [MSC3589](https://github.com/matrix-org/matrix-spec-proposals/pull/3589).

changelogs/server_server/newsfragments/1032.clarification

@@ -0,0 +1 @@
+Update various links which pointed to the old `matrix-doc` github repository.

changelogs/server_server/newsfragments/1038.clarification

@@ -0,0 +1 @@
+Clarify the format for the Authorization header.

changelogs/server_server/newsfragments/1045.clarification

@@ -0,0 +1 @@
+Clarify what a "valid event" means when performing checks on a received PDU.

changelogs/server_server/newsfragments/1055.clarification

@@ -0,0 +1 @@
+Clarify that `valid_until_ts` is in milliseconds, like other timestamps used in Matrix.

changelogs/server_server/newsfragments/1067.clarification

@@ -0,0 +1 @@
+Clarify the format for the Authorization header.

changelogs/server_server/newsfragments/1067.feature

@@ -0,0 +1 @@
+Add a `destination` property to the Authorization header, as per [MSC3383](https://github.com/matrix-org/matrix-spec-proposals/pull/3383).

changelogs/server_server/newsfragments/1070.clarification

@@ -0,0 +1 @@
+Clarify that checks on PDUs should refer to the state *before* an event.

changelogs/server_server/newsfragments/1099.clarification

@@ -0,0 +1 @@
+Clarify the historical handling of non-integer power levels.

changelogs/server_server/newsfragments/1110.clarification

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

changelogs/server_server/newsfragments/3703.clarification

@@ -0,0 +1 @@
+Correct misleading text for `/send_join` response.

changelogs/server_server/newsfragments/3727.clarification

@@ -0,0 +1 @@
+Clarify that the `content` for `X-Matrix` signature validation is the parsed JSON body.

changelogs/server_server/newsfragments/998.clarification

@@ -0,0 +1 @@
+Remove largely unused `origin` field from PDUs.

changelogs/template.md.jinja

@@ -1,24 +0,0 @@
-{% for section_name, section in sections.items() %}
-{% if section_name %}
-
-## {{section_name}}
-{% endif %}
-
-{% if section %}
-{% for category, val in definitions.items() if category in section %}
-**{{ definitions[category]['name'] }}**
-
-{% for content, issues in section[category].items() %}
-- {{ content }} (
-{%- for issue in issues %}
-[{{issue}}](https://github.com/matrix-org/matrix-spec/issues/{{issue|trim('#')}}){% if not loop.last %}, {% endif %}
-{%- endfor %}
-)
-{% endfor %}
-
-{% endfor %}
-{% else %}
-No significant changes.
-
-{% endif %}
-{% endfor %}

config.toml

@@ -0,0 +1,106 @@
+baseURL = "/"
+title = "Matrix Specification"
+
+# Prepends absolute URLs with the baseURL. Useful when hosting on non-root
+# paths, such as /unstable.
+canonifyURLs = true
+
+enableRobotsTXT = true
+
+# Hugo allows theme composition (and inheritance). The precedence is from left to right.
+theme = ["docsy"]
+
+disableKinds = ["taxonomy", "taxonomyTerm"]
+
+[languages]
+[languages.en]
+title = "Matrix Specification"
+description = "Home of the Matrix specification for decentralised communication"
+languageName ="English"
+# Weight used for sorting.
+weight = 1
+
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.renderer]
+      # Enables us to render raw HTML
+      unsafe = true
+  [markup.highlight]
+      # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
+      # If the style is changed, remember to regenerate the CSS with:
+      #
+      #   hugo gen chromastyles --style=<style> > assets/scss/syntax.scss
+      style = "tango"
+
+      # we enable CSS classes (instead of using inline styles) for compatibility with the CSP.
+      noClasses = false
+
+# Everything below this are Site Params
+
+[params]
+copyright = "The Matrix.org Foundation CIC"
+privacy_policy = "https://matrix.org/legal/privacy-notice"
+
+[params.version]
+# must be one of "unstable", "current", "historical"
+# this is used to decide whether to show a banner pointing to the current release
+status = "stable"
+# A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
+current_version_url = "https://spec.matrix.org/latest"
+# The following is used when status = "stable", and is displayed in various UI elements on a released version
+# of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
+major = "1"
+minor = "3"
+release_date = "June 16, 2022"
+
+# User interface configuration
+[params.ui]
+# Set to true to disable the About link in the site footer
+footer_about_disable = false
+# Collapse HTTP API and event <details> elements
+rendered_data_collapsed = false
+
+[params.links]
+# End user relevant links. These will show up on left side of footer and in the community page if you have one.
+# [[params.links.user]]
+# 	name = "User mailing list"
+# 	url = "https://example.org/mail"
+# 	icon = "fa fa-envelope"
+#         desc = "Discussion and help from your fellow users"
+# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
+[[params.links.developer]]
+	name = "GitHub"
+	url = "https://github.com/matrix-org"
+	icon = "fab fa-github"
+  desc = "Matrix on GitHub"
+[[params.links.developer]]
+	name = "GitLab"
+	url = "https://gitlab.matrix.org/matrix-org"
+	icon = "fab fa-gitlab"
+  desc = "Matrix on GitLab"
+[[params.links.developer]]
+	name = "YouTube"
+	url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
+	icon = "fab fa-youtube"
+  desc = "Matrix YouTube channel"
+[[params.links.developer]]
+	name = "Twitter"
+	url = "https://twitter.com/matrixdotorg"
+	icon = "fab fa-twitter"
+  desc = "Matrix on Twitter"
+
+
+# configuration for the hugo development server
+[server]
+
+# set HTTP response headers to match the production site. Compare the Apache config for `spec.matrix.org`.
+[[server.headers]]
+  for = '/**'
+  [server.headers.values]
+    Content-Security-Policy = "default-src 'self'; style-src 'self'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
+    X-XSS-Protection = "1; mode=block"
+    X-Content-Type-Options = "nosniff"
+    # Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
+    X-Frame-Options = "sameorigin"
+    Access-Control-Allow-Origin = "*"
+    Access-Control-Allow-Methods = "GET"

config/_default/hugo.toml

@@ -1,168 +0,0 @@
-# Default settings.
-
-baseURL = "/"
-title = "Matrix Specification"
-
-enableRobotsTXT = true
-
-# We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
-# links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
-# contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
-disableKinds = ["taxonomy", "rss"]
-
-[languages]
-[languages.en]
-title = "Matrix Specification"
-languageName ="English"
-# Weight used for sorting.
-weight = 1
-[languages.en.params]
-description = "Home of the Matrix specification for decentralised communication"
-
-# Entries in the main menu in the header.
-[menus]
-[[menus.main]]
-    name = 'Foundation'
-    url = 'https://matrix.org/foundation/about/'
-    weight = 10
-[[menus.main]]
-    name = 'User Docs'
-    url = 'https://matrix.org/docs/'
-    weight = 20
-[[menus.main]]
-    name = 'Blog'
-    url = 'https://matrix.org/blog/'
-    weight = 30
-
-[markup]
-  [markup.tableOfContents]
-    startLevel = 2
-    endLevel = 6
-    ordered = true
-  [markup.goldmark]
-    [markup.goldmark.renderer]
-      # Enables us to render raw HTML
-      unsafe = true
-    [markup.goldmark.extensions]
-      # Tell Goldmark to pass delimited blocks through the `render-passthrough` render hook.
-      # This is used to render the maths in the Olm spec.
-      # See: https://gohugo.io/functions/transform/tomath/#step-1.
-      [markup.goldmark.extensions.passthrough]
-        enable = true
-        [markup.goldmark.extensions.passthrough.delimiters]
-          block = [['\[', '\]']]
-          inline = [['\(', '\)']]
-  [markup.highlight]
-      # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
-      # If the style is changed, remember to regenerate the CSS with:
-      #
-      #   hugo gen chromastyles --style=<style> > assets/scss/syntax.scss
-      style = "tango"
-
-      # we enable CSS classes (instead of using inline styles) for compatibility with the CSP.
-      noClasses = false
-
-# Everything below this are Site Params
-
-[params]
-copyright = "The Matrix.org Foundation CIC"
-
-[params.version]
-# must be one of "unstable", "current", "historical"
-# this is used to decide whether to show a banner pointing to the current release
-status = "unstable"
-# A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
-current_version_url = "https://spec.matrix.org/latest"
-# The following is used when status = "stable", and is displayed in various UI elements on a released version
-# of the spec.
-#major = "1"
-#minor = "17"
-
-[[params.versions]]
-# We must include this parameter to enable docsy's version picker in the navbar. The picker
-# is populated automatically in navbar-version-selector.html.
-
-# User interface configuration
-[params.ui]
-# Collapse HTTP API and event <details> elements
-rendered_data_collapsed = false
-# Hide the search entry in the sidebar
-sidebar_search_disable = true
-# Only show the current page's ancestors, siblings and direct descendants in the sidebar menu
-sidebar_menu_compact = true
-
-[params.links]
-# End user relevant links. These will show up on left side of footer and in the community page if you have one.
-# [[params.links.user]]
-# 	name = "User mailing list"
-# 	url = "https://example.org/mail"
-# 	icon = "fa fa-envelope"
-#         desc = "Discussion and help from your fellow users"
-# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
-# [[params.links.developer]]
-# 	name = "GitHub"
-# 	url = "https://github.com/matrix-org"
-# 	icon = "fab fa-github"
-#   desc = "Matrix on GitHub"
-# Custom links shown in the center of the footer. (Only supported by our fork of docsy's 'footer/central' partial.)
-[[params.links.bottom]]
-  name = "GitHub"
-  url = "https://github.com/matrix-org"
-  icon = "fab fa-github"
-  desc = "Matrix on GitHub"
-[[params.links.bottom]]
-  name = "GitLab"
-  url = "https://gitlab.matrix.org/matrix-org"
-  icon = "fab fa-gitlab"
-  desc = "Matrix on GitLab"
-[[params.links.bottom]]
-  name = "YouTube"
-  url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
-  icon = "fab fa-youtube"
-  desc = "Matrix YouTube channel"
-[[params.links.bottom]]
-  name = "Mastodon"
-  url = "https://mastodon.matrix.org/@matrix"
-  icon = "fab fa-mastodon"
-  desc = "Matrix on Mastodon"
-[[params.links.bottom]]
-  name = "Bluesky"
-  url = "https://bsky.app/profile/matrix.org"
-  icon = "fab fa-bluesky"
-  desc = "Matrix on Bluesky"
-
-
-# configuration for the hugo development server
-[server]
-
-# set HTTP response headers to match the production site. Compare the Apache config for `spec.matrix.org`.
-[[server.headers]]
-  for = '/**'
-  [server.headers.values]
-    # `style-src 'unsafe-inline'` is needed to correctly render the maths in the Olm spec:
-    # https://github.com/KaTeX/KaTeX/issues/4096
-    Content-Security-Policy = "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
-    X-XSS-Protection = "1; mode=block"
-    X-Content-Type-Options = "nosniff"
-    # Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
-    X-Frame-Options = "sameorigin"
-    Access-Control-Allow-Origin = "*"
-    Access-Control-Allow-Methods = "GET"
-
-# hugo module configuration
-
-[module]
-  [module.hugoVersion]
-    extended = true
-    min = "0.146.0"
-  [[module.imports]]
-    path = "github.com/matrix-org/docsy"
-    disable = false
-
-# custom output formats
-
-[outputFormats]
-  [outputFormats.Checklist]
-    mediaType = "text/markdown"
-    isPlainText = true
-    baseName = "checklist"

config/production/hugo.toml

@@ -1,6 +0,0 @@
-# Settings only required when the website is built for production.
-
-# Enable stats to use them to optimize the CSS.
-[build]
-  [build.buildStats]
-    enable = true

content/_index.md

@@ -25,14 +25,14 @@ The specification consists of the following parts:
 * [Identity Service API](/identity-service-api)
 * [Push Gateway API](/push-gateway-api)
 * [Room Versions](/rooms)
-* [Olm & Megolm](/olm-megolm)
 * [Appendices](/appendices)
 
 Additionally, this introduction page contains the key baseline
 information required to understand the specific APIs, including the
 section the [overall architecture](#architecture).
 
-The [Matrix API Viewer](https://matrix.org/docs/api/) is useful for
+The [Matrix Client-Server API Swagger
+Viewer](https://matrix.org/docs/api/client-server/) is useful for
 browsing the Client-Server API.
 
 ## Introduction to the Matrix APIs
@@ -57,6 +57,9 @@ The principles that Matrix attempts to follow are:
         the global Matrix network
     -   Fully open standard - publicly documented standard with no IP or
         patent licensing encumbrances
+    -   Fully open source reference implementation - liberally-licensed
+        example implementations with no IP or patent licensing
+        encumbrances
 -   Empowering the end-user
     -   The user should be able to choose the server and clients they
         use
@@ -97,20 +100,6 @@ services - be that for instant messages, VoIP call setups, or any other
 objects that need to be reliably and persistently pushed from A to B in
 an interoperable and federated manner.
 
-### Requirement levels
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" across all parts of the
-specification are to be interpreted as described in
-[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
-
-Some entire sections of the specification might be optional depending on the
-circumstances. For example, the
-[modules of the client-server API](/client-server-api/#modules)
-apply depending on the use case. The requirement level expressed by the above
-key words appearing in such a section is only relevant if the section itself is
-applicable.
-
 ### Spec Change Proposals
 
 To propose a change to the Matrix Spec, see the explanations at
@@ -152,7 +141,7 @@ request.
 
 How data flows between clients:
 
-```nohighlight
+```
     { Matrix client A }                             { Matrix client B }
         ^          |                                    ^          |
         |  events  |  Client-Server API                 |  events  |
@@ -369,8 +358,8 @@ servers that are in the room that can be used to join via.
 
     HTTP GET
     #matrix:example.org      !aaabaa:matrix.org
-           |                    ^
+       |                    ^
-           |                    |
+       |                    |
     _______V____________________|____
     |          example.org           |
     | Mappings:                      |
@@ -384,7 +373,7 @@ servers that are in the room that can be used to join via.
 Users in Matrix are identified via their Matrix user ID. However,
 existing 3rd party ID namespaces can also be used in order to identify
 Matrix users. A Matrix "Identity" describes both the user ID and any
-other existing IDs from third-party namespaces *linked* to their
+other existing IDs from third party namespaces *linked* to their
 account. Matrix users can *link* third-party IDs (3PIDs) such as email
 addresses, social network accounts and phone numbers to their user ID.
 Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping
@@ -431,16 +420,9 @@ into the `m.` namespace.
 
 ### Timestamps
 
-Unless otherwise stated, timestamps are the number of milliseconds
+Unless otherwise stated, timestamps are measured as milliseconds since
-elapsed since the unix epoch (1970-01-01 00:00:00 UTC), but not counting
+the Unix epoch. Throughout the specification this may be referred to as
-leap seconds, so that each day is precisely 86,400,000 milliseconds.
+POSIX, Unix, or just "time in milliseconds".
-
-This means that timestamps can repeat during leap seconds. Most
-programming languages provide timestamps in that format natively, e.g.
-[ECMAScript](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-time-values-and-time-range).
-Throughout the specification this may be referred to as POSIX,
-[Unix](https://en.wikipedia.org/wiki/Unix_time), or just "time in
-milliseconds".
 
 ## Specification Versions
 
@@ -505,23 +487,18 @@ For historical reference, the APIs were versioned as `rX.Y.Z` where `X`
 roughly represents a breaking change, `Y` a backwards-compatible change, and
 `Z` a patch or insignificant alteration to the API.
 
-The current global versioning system was introduced with `v1.1`.
+`v1.0` of Matrix was released on June 10th, 2019 with the following API
-[Matrix 1.0](https://matrix.org/blog/2019/06/11/introducing-matrix-1-0-and-the-matrix-org-foundation/)
+versions:
-did not correspond directly to a specification version; instead, it was based on
-the following versions for the individual APIs:
 
-| API/Specification        | Version       |
+| API/Specification       | Version |
-|--------------------------|---------------|
+|-------------------------|---------|
-| Client-Server API        | r0.5.0        |
+| Client-Server API       | r0.5.0  |
-| Server-Server API        | r0.1.2        |
+| Server-Server API       | r0.1.2  |
-| Application Service API  | r0.1.1        |
+| Application Service API | r0.1.1  |
-| Identity Service API     | r0.2.0        |
+| Identity Service API    | r0.1.1  |
-| Push Gateway API         | r0.1.0        |
+| Push Gateway API        | r0.1.0  |
-| Room Versions            | 1, 2, 3, 4, 5 |
+| Room Version            | v5      |
 
-`v1.0` should **not** be returned by servers in the
-[`GET /_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
-response.
 
 ## License