Merge pull request #2992 from wbamberg/support-changelogs

Support changelogs

changelogs/client_server/newsfragments/2387.new

@@ -1 +1 @@
-Add key backup (``/room_keys/*``) endpoints.
+Add key backup (`/room_keys/*`) endpoints.

changelogs/client_server/newsfragments/2399.feature

@@ -1 +1 @@
-Document how clients can advise recipients that it is withholding decryption keys as per `MSC2399 <https://github.com/matrix-org/matrix-doc/pull/2399>`_.
+Document how clients can advise recipients that it is withholding decryption keys as per [MSC2399](https://github.com/matrix-org/matrix-doc/pull/2399).

changelogs/client_server/newsfragments/2536.feature

@@ -1 +1 @@
-Add cross-signing properties to the response of ``POST /keys/query`` per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).
+Add cross-signing properties to the response of `POST /keys/query` per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).

changelogs/client_server/newsfragments/2536.new

@@ -1 +1 @@
-Add ``POST /keys/device_signing/upload`` and ``POST /keys/signatures/upload`` per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).
+Add `POST /keys/device_signing/upload` and `POST /keys/signatures/upload` per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).

changelogs/client_server/newsfragments/2591.clarification

@@ -1 +1 @@
-Fix issues with ``age`` and ``unsigned`` being shown in the wrong places.
+Fix issues with `age` and `unsigned` being shown in the wrong places.

changelogs/client_server/newsfragments/2609.removal

@@ -1 +1 @@
-Remove unimplemented ``m.login.oauth2`` and ``m.login.token`` user-interactive authentication mechanisms.
+Remove unimplemented `m.login.oauth2` and `m.login.token` user-interactive authentication mechanisms.

changelogs/client_server/newsfragments/2629.clarification

@@ -1 +1 @@
-Remove ``room_id`` from ``/sync`` examples.
+Remove `room_id` from `/sync` examples.

changelogs/client_server/newsfragments/2647.clarification

@@ -1 +1 @@
-Improve consistency and clarity of event schema ``title``\ s.
+Improve consistency and clarity of event schema `title` s.

changelogs/client_server/newsfragments/2709.feature

@@ -1 +1 @@
-Add a ``device_id`` parameter to login fallback per `MSC2604 <https://github.com/matrix-org/matrix-doc/pull/2604>`_.
+Add a `device_id` parameter to login fallback per [MSC2604](https://github.com/matrix-org/matrix-doc/pull/2604).

changelogs/client_server/newsfragments/2754.clarification

@@ -1 +1 @@
-Clarify the behaviour of ``state`` for ``/sync`` with lazy-loading.
+Clarify the behaviour of `state` for `/sync` with lazy-loading.

changelogs/client_server/newsfragments/2795.feature

@@ -1 +1 @@
-Added support for ``reason`` on all membership events and related endpoints as per `MSC2367 <https://github.com/matrix-org/matrix-doc/pull/2367>`_.
+Added support for `reason` on all membership events and related endpoints as per [MSC2367](https://github.com/matrix-org/matrix-doc/pull/2367).

changelogs/client_server/newsfragments/2796.feature

@@ -1 +1 @@
-Add a 404 ``M_NOT_FOUND`` error to push rule endpoints as per `MSC2663 <https://github.com/matrix-org/matrix-doc/pull/2663>`_.
+Add a 404 `M_NOT_FOUND` error to push rule endpoints as per [MSC2663](https://github.com/matrix-org/matrix-doc/pull/2663).

changelogs/client_server/newsfragments/2807.feature

@@ -1 +1 @@
-Make ``reason`` and ``score`` parameters optional in the content reporting API (MSC2414).
+Make `reason` and `score` parameters optional in the content reporting API (MSC2414).

changelogs/server_server/newsfragments/2536.feature

@@ -1,9 +1,9 @@
 Add cross-signing:
 
-- Add properties to the response of ``GET /user/keys`` and ``GET
+- Add properties to the response of `GET /user/keys` and `GET
-  /user/devices/{userId}``.
+  /user/devices/{userId}`.
-- The ``m.device_list_update`` EDU is sent when a device gets a new signature.
+- The `m.device_list_update` EDU is sent when a device gets a new signature.
-- A new ``m.signing_key_update`` EDU is sent when a user's cross-signing keys
+- A new `m.signing_key_update` EDU is sent when a user's cross-signing keys
   are changed.
 
 per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).

changelogs/server_server/newsfragments/2688.clarification

@@ -1 +1 @@
-Specify that ``GET /_matrix/federation/v1/make_join/{roomId}/{userId}`` can return a 404 if the room is unknown.
+Specify that `GET /_matrix/federation/v1/make_join/{roomId}/{userId}` can return a 404 if the room is unknown.

config.toml

@@ -39,7 +39,7 @@ privacy_policy = "https://matrix.org/legal/privacy-notice"
 # must be one of "unstable", "current", "historical"
 # this is used to decide whether to show a banner pointing to the current release
 status = "unstable"
-current_version_url = "https://spec.matrix.org/latest"
+current_version_url = "https://matrix.org/docs/spec/"
 
 # User interface configuration
 [params.ui]

content/changelog.md

@@ -0,0 +1,47 @@
+---
+title: Changelog
+type: docs
+weight: 1000
+---
+
+{{% changelog/changelog-description %}}
+
+{{% changelog/changelog-changes %}}
+
+<h2 id="historical-versions" class="no-numbers">Historical versions</h2>
+
+Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs.
+
+* **Client-Server API**
+  -   [r0.6.1](https://matrix.org/docs/spec/client_server/r0.6.1.html)
+  -   [r0.6.0](https://matrix.org/docs/spec/client_server/r0.6.0.html)
+  -   [r0.5.0](https://matrix.org/docs/spec/client_server/r0.5.0.html)
+  -   [r0.4.0](https://matrix.org/docs/spec/client_server/r0.4.0.html)
+  -   [r0.3.0](https://matrix.org/docs/spec/client_server/r0.3.0.html)
+  -   [r0.2.0](https://matrix.org/docs/spec/client_server/r0.2.0.html)
+  -   [r0.1.0](https://matrix.org/docs/spec/client_server/r0.1.0.html)
+  -   [r0.0.1](https://matrix.org/docs/spec/r0.0.1/client_server.html)
+  -   [r0.0.0](https://matrix.org/docs/spec/r0.0.0/client_server.html)
+  -   [Legacy](https://matrix.org/docs/spec/legacy/#client-server-api):
+      The last draft before the spec was formally released in version
+      r0.0.0.
+
+* **Server-Server API**
+  -   [r0.1.4](https://matrix.org/docs/spec/server_server/r0.1.4.html)
+  -   [r0.1.3](https://matrix.org/docs/spec/server_server/r0.1.3.html)
+  -   [r0.1.2](https://matrix.org/docs/spec/server_server/r0.1.2.html)
+  -   [r0.1.1](https://matrix.org/docs/spec/server_server/r0.1.1.html)
+  -   [r0.1.0](https://matrix.org/docs/spec/server_server/r0.1.0.html)
+
+* **Application Service API**
+  -   [r0.1.1](https://matrix.org/docs/spec/application_service/r0.1.1.html)
+  -   [r0.1.0](https://matrix.org/docs/spec/application_service/r0.1.0.html)
+
+* **Identity Service API**
+  -   [r0.3.0](https://matrix.org/docs/spec/identity_service/r0.3.0.html)
+  -   [r0.2.1](https://matrix.org/docs/spec/identity_service/r0.2.1.html)
+  -   [r0.2.0](https://matrix.org/docs/spec/identity_service/r0.2.0.html)
+  -   [r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html)
+
+* **Push Gateway API**
+  -   [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html)

layouts/partials/navbar.html

@@ -45,8 +45,7 @@
     {{ $status := .Site.Params.version.status }}
 
     {{ if ne $status "unstable"}}
-        {{ $version_pieces := slice .Site.Params.version.major_version .Site.Params.version.minor_version .Site.Params.version.patch_version}}
+        {{ $ret = .Site.Params.version.number }}
-        {{ $ret = delimit $version_pieces "." }}
         {{ $ret = delimit (slice "version" $ret) " " }}
     {{ end }}
 

layouts/shortcodes/changelog/changelog-changes.html

@@ -0,0 +1,83 @@
+{{/*
+
+  This template is used to render the set of changes in the changelog page.
+
+  It expects to find a directory "changelogs" containing a subdirectory for
+  each of the 5 APIs in the specification. Inside each of these directories
+  it expects to find newsfragments describing changes to that API.
+
+  If the `version.status` setting in config.toml is anything other than
+  "unstable", then it also expects to find a "release.yaml" file in /changelogs,
+  which contains:
+  - `tag`: Git tag for this release
+  - `date`: date of this release
+  It then renders this info a table, before the list of changes.
+
+*/}}
+
+{{ $path := path.Join "changelogs" }}
+{{ $status := .Site.Params.version.status }}
+
+{{ if ne $status "unstable" }}
+{{ $release_info := readFile (path.Join $path "release.yaml") | transform.Unmarshal }}
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/{{ $release_info.tag }}">https://github.com/matrix-org/matrix-doc/tree/{{ $release_info.tag }}</a></td>
+<tr><th>Release date</th><td>{{ $release_info.date }}</td>
+</table>
+{{ end }}
+
+<h2 id=api-changes>Changes since last release</h2>
+{{ partial "render-api-changes" (dict "title" "Client-Server API" "id" "client-server-api" "path" (path.Join $path "client_server")) }}
+{{ partial "render-api-changes" (dict "title" "Server-Server API" "id" "server-server-api" "path" (path.Join $path "server_server")) }}
+{{ partial "render-api-changes" (dict "title" "Application Service API" "id" "application-service-api" "path" (path.Join $path "application_service")) }}
+{{ partial "render-api-changes" (dict "title" "Identity Service API" "id" "identity-service-api" "path" (path.Join $path "identity_service")) }}
+{{ partial "render-api-changes" (dict "title" "Push Gateway API" "id" "push-gateway-api" "path" (path.Join $path "push_gateway")) }}
+
+{{ define "partials/render-api-changes" }}
+<h3 id="{{.id}}">{{ .title }}</h3>
+    {{ $api_path := .path }}
+    {{ $config_file := path.Join $api_path "pyproject.toml" }}
+    {{ $config := readFile $config_file | transform.Unmarshal }}
+    {{ $news_path := path.Join $api_path "newsfragments" }}
+    {{ partial "render-newsfragments"  (dict "config" $config "news_path" $news_path )}}
+{{ end }}
+
+{{ define "partials/render-newsfragments" }}
+{{ $config := .config }}
+{{ $news_path := .news_path }}
+
+{{ $types := dict }}
+{{ range $config.tool.towncrier.type }}
+    {{ $types = merge $types (dict .directory (slice)) }}
+{{ end }}
+
+{{ range (readDir $news_path) }}
+
+    {{ $pieces := split .Name "." }}
+
+    {{ $ticket := index $pieces 0 }}
+    {{ $description := readFile (path.Join $news_path .Name ) }}
+    {{ $change_info := (dict "ticket" $ticket "description" $description )}}
+
+    {{ $type := index $pieces 1 }}
+    {{ $instances := index $types $type }}
+    {{ $instances = $instances | append $change_info }}
+    {{ $types = merge $types (dict $type $instances) }}
+
+{{ end }}
+
+<ul>
+{{ range $config.tool.towncrier.type }}
+    {{ $changes_of_type := (index $types .directory) }}
+    {{ if $changes_of_type }}
+<li><strong>{{.name}}</strong>
+<p><ul>
+        {{ range $changes_of_type }}
+<li><a href="https://github.com/matrix-org/matrix-doc/issues/{{.ticket}}"><strong>{{ .ticket }}: </strong></a>{{ .description | markdownify }}</li>
+        {{ end }}
+</ul></p>
+</li>
+    {{ end }}
+{{ end }}
+</ul>
+{{ end }}

layouts/shortcodes/changelog/changelog-description.html

@@ -0,0 +1,15 @@
+{{/*
+
+  This template is used to provide different content for the unstable spec
+  version and for a versioned release.
+
+*/}}
+
+{{ $status := .Site.Params.version.status }}
+
+{{ if eq $status "unstable"}}
+<p>This is the <strong>unstable</strong> version of the Matrix specification.</p>
+<p>This changelog lists changes made since the last release of the specification.</p>
+{{ else }}
+<p>This is version <strong>{{ .Site.Params.version.number }}</strong> of the Matrix specification.</p>
+{{ end }}