Generate unstable changelogs using towncrier

.github/workflows/main.yml

@@ -99,10 +99,28 @@ jobs:
           name: openapi-artifact
           path: openapi.tar.gz
 
+  generate-changelog:
+    name: "📢 Run towncrier for changelog"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v2
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v4
+      - name: "➕ Install towncrier"
+        run: "pip install 'towncrier'"
+      - name: "Generate changelog"
+        run: ./scripts/generate-changelog.sh vUNSTABLE
+      - name: "📤 Artifact upload"
+        uses: actions/upload-artifact@v2
+        with:
+          name: changelog-artifact
+          path: content/changelog/vUNSTABLE.md
+
   build-spec:
     name: "📖 Build the spec"
     runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-openapi]
+    needs: [calculate-baseurl, build-openapi, generate-changelog]
     steps:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v2
@@ -119,9 +137,13 @@ jobs:
         run: |
           npm i
           npm run get-proposals
+      - name: "📥 Download generated changelog"
+        uses: actions/download-artifact@v3
+        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

content/changelog/index.md

@@ -6,8 +6,6 @@ weight: 1000
 
 {{% changelog/changelog-description %}}
 
-{{% changelog/changelog-changes %}}
-
 {{% changelog/changelogs %}}
 
 <h2 id="historical-versions" class="no-numbers">Historical versions</h2>

layouts/shortcodes/changelog/changelog-changes.html

@@ -1,90 +0,0 @@
-{{/*
-
-  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 additional settings under
-  `version` in config.toml:
-  - `major`: the major version number of the release
-  - `minor`: the minor version number of the release
-  - `release_date`: the date of the release
-
-  The release tag is calculated as `v<major>.<minor>`; for example `v1.5`.
-
-  It then renders this into a table displayed before the list of changes.
-
-*/}}
-
-{{ $path := path.Join "changelogs" }}
-{{ $status := .Site.Params.version.status }}
-{{ $release_tag := delimit (slice "v" .Site.Params.version.major "." .Site.Params.version.minor) "" }}
-
-{{ if ne $status "unstable" }}
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/{{ $release_tag }}">https://github.com/matrix-org/matrix-spec/tree/{{ $release_tag }}</a></td>
-<tr><th>Release date</th><td>{{ .Site.Params.version.release_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")) }}
-{{ partial "render-api-changes" (dict "title" "Room Versions" "id" "room-versions" "path" (path.Join $path "room_versions")) }}
-{{ partial "render-api-changes" (dict "title" "Appendices" "id" "appendices" "path" (path.Join $path "appendices")) }}
-{{ partial "render-api-changes" (dict "title" "Internal Changes/Tooling" "id" "internal" "path" (path.Join $path "internal")) }}
-
-{{ 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>{{.name | safeHTML}}
-<p><ul>
-        {{ range $changes_of_type }}
-<li><a href="https://github.com/matrix-org/matrix-spec/issues/{{.ticket}}"><strong>{{ .ticket }}: </strong></a>{{ .description | markdownify }}</li>
-        {{ end }}
-</ul></p>
-</li>
-    {{ end }}
-{{ end }}
-</ul>
-{{ end }}

scripts/generate-changelog.sh

@@ -1,13 +1,17 @@
 # /bin/bash
 
-# Usage: ./generate.sh v1.2 "April 01, 2021"
+# Usage: ./scripts/generate-changelog.sh v1.2 "April 01, 2021"
+# or: ./scripts/generate-changelog.sh vUNSTABLE
 
 set -e
 
-cd changelogs
+VERSION="$1"
+DATE="$2"
+
+cd `dirname $0`/../changelogs
 
 # Pre-cleanup just in case it wasn't done on the last run
-rm -f rendered.*
+rm -f rendered.md
 
 # Reversed order so that room versions ends up on the bottom
 towncrier --name "Internal Changes/Tooling" --dir "./internal" --config "./pyproject.toml" --yes
@@ -19,17 +23,19 @@ towncrier --name "Application Service API" --dir "./application_service" --confi
 towncrier --name "Server-Server API" --dir "./server_server" --config "./pyproject.toml" --yes
 towncrier --name "Client-Server API" --dir "./client_server" --config "./pyproject.toml" --yes
 
-# Prepare the header
-cp header.md rendered.header.md
-sed -i "s/VERSION/$1/g" rendered.header.md
-sed -i "s/DATE/$2/g" rendered.header.md
-cat rendered.header.md rendered.md > rendered.final.md
+{
+    # Prepare the header
+    if [ "$VERSION" = "vUNSTABLE" ]; then
+        cat <<EOF
+## Changes since last release
+EOF
+    else
+        sed -e "s/VERSION/$1/g" -e "s/DATE/$2/g" header.md
+    fi
 
-# Remove trailing whitespace (such as our intentionally blank RST headings)
-sed -i "s/[ ]*$//" rendered.final.md
-
-# Put the changelog in place
-mv rendered.final.md ../content/changelogs/$1.md
+    # Remove trailing whitespace (such as our intentionally blank RST headings)
+    sed -e "s/[ ]*$//" rendered.md
+} > ../content/changelog/$VERSION.md
 
 # Cleanup
-rm -v rendered.*
+rm -v rendered.md