Provide MD checklists for the changelog (#1937)

* Output changelog checklists Fixes: #1682 Signed-off-by: Johannes Marbach <[email protected]>
matrix-org · Sep 27, 2024 · 00af39e · 00af39e
1 parent ace2712
commit 00af39e
Show file tree

Hide file tree

Showing 22 changed files with 219 additions and 151 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -177,7 +177,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: changelog-artifact
-          path: content/changelog/vUNSTABLE.md
+          path: content/changelog/unstable.md
 
   build-spec:
     name: "📖 Build the spec"

diff --git a/changelogs/header.md b/changelogs/header.md
@@ -6,11 +6,10 @@ Variables:
     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>
+<tr><th>Checklist</th><td><a href="/changelog/VERSION/checklist.md">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
diff --git a/changelogs/internal/newsfragments/1937.clarification b/changelogs/internal/newsfragments/1937.clarification
@@ -0,0 +1 @@
+Provide markdown checklists for changelogs under `/changelog/$VERSION/checklist.md`.
diff --git a/changelogs/template.md.jinja b/changelogs/template.md.jinja
@@ -1,7 +1,7 @@
 {% for section_name, section in sections.items() %}
 {% if section_name %}
 
-### {{section_name}}
+## {{section_name}}
 {% endif %}
 
 {% if section %}

diff --git a/config.toml b/config.toml
@@ -138,3 +138,11 @@ sidebar_menu_compact = true
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false
+
+# custom output formats
+
+[outputFormats]
+  [outputFormats.Checklist]
+    mediaType = "text/markdown"
+    isPlainText = true
+    baseName = "checklist"
diff --git a/content/changelog/_index.md b/content/changelog/_index.md
@@ -0,0 +1,7 @@
+---
+title: Changelog
+type: docs
+weight: 1000
+---
+
+{{% changelog/changelogs %}}
diff --git a/content/changelog/index.md → content/changelog/historical.md b/content/changelog/index.md → content/changelog/historical.md
@@ -1,18 +1,15 @@
 ---
-title: Changelog
+title: Historical versions
 type: docs
-weight: 1000
+outputs:
+  - html
 ---
 
-{{% changelog/changelog-description %}}
+Before version 1.1, versioning was applied at the level of individual API specifications.
+This section includes links to these versions of the APIs.
 
-{{% changelog/changelogs %}}
+## Client-Server API
 
-<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)
@@ -26,22 +23,26 @@ Before version 1.1, versioning was applied at the level of individual API specif
       The last draft before the spec was formally released in version
       r0.0.0.
 
-* **Server-Server API**
+## 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**
+## 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**
+## 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**
+## Push Gateway API
+
   -   [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html)
diff --git a/content/changelog/v1.1.md b/content/changelog/v1.1.md
@@ -1,4 +1,10 @@
 ---
+title: v1.1 Changelog
+linkTitle: v1.1
+type: docs
+outputs:
+  - html
+  - checklist
 date: 2021-11-09T00:00:00+0000
 ---
 <!--
@@ -9,15 +15,14 @@ Variables:
     November 09, 2021     = Replaced by the date (eg: April 01, 2021)
 -->
 
-## v1.1
-
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.1">https://github.com/matrix-org/matrix-doc/tree/v1.1</a></td>
 <tr><th>Release date</th><td>November 09, 2021</td>
+<tr><th>Checklist</th><td><a href="/changelog/v1.1/checklist.md">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -110,7 +115,7 @@ Variables:
 - Fix documentation errors around `threepid_creds`. ([#3471](https://github.com/matrix-org/matrix-doc/issues/3471))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>New Endpoints</strong>
@@ -136,7 +141,7 @@ Variables:
 - Tweak the example PDU diagram to better demonstrate situations with multiple `prev_events`. ([#3340](https://github.com/matrix-org/matrix-doc/issues/3340))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -145,7 +150,7 @@ Variables:
 - Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>New Endpoints</strong>
@@ -168,7 +173,7 @@ Variables:
 - Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3459](https://github.com/matrix-org/matrix-doc/issues/3459))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>

diff --git a/content/changelog/v1.10.md b/content/changelog/v1.10.md
@@ -1,4 +1,10 @@
 ---
+title: v1.10 Changelog
+linkTitle: v1.10
+type: docs
+outputs:
+  - html
+  - checklist
 date: 2024-03-22T09:59:45-06:00
 ---
 <!--
@@ -9,16 +15,15 @@ Variables:
     March 22, 2024     = Replaced by the date (eg: April 01, 2021)
 -->
 
-## v1.10
-
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.10">https://github.com/matrix-org/matrix-spec/tree/v1.10</a></td>
 <tr><th>Release date</th><td>March 22, 2024</td>
+<tr><th>Checklist</th><td><a href="/changelog/v1.10/checklist.md">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
-### Client-Server API
+## Client-Server API
 
 **Backwards Compatible Changes**
 
@@ -50,7 +55,7 @@ Variables:
 - Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763))
 
 
-### Server-Server API
+## Server-Server API
 
 **Spec Clarifications**
 
@@ -59,36 +64,36 @@ Variables:
 - Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741))
 
 
-### Application Service API
+## Application Service API
 
 **Spec Clarifications**
 
 - Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744))
 
 
-### Identity Service API
+## Identity Service API
 
 No significant changes.
 
 
-### Push Gateway API
+## Push Gateway API
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 **Spec Clarifications**
 
 - For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717))
 
 
-### Appendices
+## Appendices
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 **Spec Clarifications**
 

diff --git a/content/changelog/v1.11.md b/content/changelog/v1.11.md
@@ -1,4 +1,10 @@
 ---
+title: v1.11 Changelog
+linkTitle: v1.11
+type: docs
+outputs:
+  - html
+  - checklist
 date: 2024-06-20T10:20:43-06:00
 ---
 <!--
@@ -9,16 +15,15 @@ Variables:
     June 20, 2024     = Replaced by the date (eg: April 01, 2021)
 -->
 
-## v1.11
-
 <table class="release-info">
 <tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.11">https://github.com/matrix-org/matrix-spec/tree/v1.11</a></td>
 <tr><th>Release date</th><td>June 20, 2024</td>
+<tr><th>Checklist</th><td><a href="/changelog/v1.11/checklist.md">checklist.md</a></td>
 </table>
 
 <!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
-### Client-Server API
+## Client-Server API
 
 **Deprecations**
 
@@ -63,7 +68,7 @@ Variables:
 - Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872))
 
 
-### Server-Server API
+## Server-Server API
 
 **Deprecations**
 
@@ -87,26 +92,26 @@ Variables:
 - Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877))
 
 
-### Application Service API
+## Application Service API
 
 **Spec Clarifications**
 
 - Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810))
 
 
-### Identity Service API
+## Identity Service API
 
 **Deprecations**
 
 - Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808))
 
 
-### Push Gateway API
+## Push Gateway API
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 **Spec Clarifications**
 
@@ -116,7 +121,7 @@ No significant changes.
 - Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884))
 
 
-### Appendices
+## Appendices
 
 **Deprecations**
 
@@ -129,7 +134,7 @@ No significant changes.
 - Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850))
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 **Spec Clarifications**