Generate changelog release info with Hugo rather than when generating changelog (#2033)

changelogs/header.md

@@ -1,15 +0,0 @@
-<!--
-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)
--->
-
-<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="{{< relref path="changelog/VERSION" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

changelogs/internal/newsfragments/2033.clarification

@@ -0,0 +1 @@
+Generate the changelog release info with Hugo, rather than the changelog generation script.

content/changelog/_index.md

@@ -4,4 +4,4 @@ type: docs
 weight: 1000
 ---
 
-{{% changelog/changelogs %}}
+<!-- This page will be redirected to the latest version's changelog -->

content/changelog/v1.1.md

@@ -2,26 +2,13 @@
 title: v1.1 Changelog
 linkTitle: v1.1
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2021-11-09T00:00:00+0000
+date: 2021-11-09
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.1  = Replaced by the version number (eg: v1.2)
-    November 09, 2021     = Replaced by the date (eg: April 01, 2021)
--->
-
-<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="{{< relref path="changelog/v1.1" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.10.md

@@ -2,26 +2,12 @@
 title: v1.10 Changelog
 linkTitle: v1.10
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-03-22T09:59:45-06:00
+date: 2024-03-22
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.10  = Replaced by the version number (eg: v1.2)
-    March 22, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-<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="{{< relref path="changelog/v1.10" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.11.md

@@ -2,26 +2,12 @@
 title: v1.11 Changelog
 linkTitle: v1.11
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-06-20T10:20:43-06:00
+date: 2024-06-20
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.11  = Replaced by the version number (eg: v1.2)
-    June 20, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-<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="{{< relref path="changelog/v1.11" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.12.md

@@ -2,26 +2,12 @@
 title: v1.12 Changelog
 linkTitle: v1.12
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-10-07T13:32:03-06:00
+date: 2024-10-07
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.12  = Replaced by the version number (eg: v1.2)
-    October 07, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.12">https://github.com/matrix-org/matrix-spec/tree/v1.12</a></td>
-<tr><th>Release date</th><td>October 07, 2024</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.12" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.13.md

@@ -2,26 +2,12 @@
 title: v1.13 Changelog
 linkTitle: v1.13
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-12-19T09:22:47-07:00
+date: 2024-12-19
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.13  = Replaced by the version number (eg: v1.2)
-    December 19, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.13">https://github.com/matrix-org/matrix-spec/tree/v1.13</a></td>
-<tr><th>Release date</th><td>December 19, 2024</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.13" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.2.md

@@ -2,26 +2,13 @@
 title: v1.2 Changelog
 linkTitle: v1.2
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-02-02T00:00:00+0000
+date: 2022-02-02
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.2  = Replaced by the version number (eg: v1.2)
-    February 02, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.2">https://github.com/matrix-org/matrix-doc/tree/v1.2</a></td>
-<tr><th>Release date</th><td>February 02, 2022</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.2" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.3.md

@@ -2,26 +2,13 @@
 title: v1.3 Changelog
 linkTitle: v1.3
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-06-15T00:00:00+0100
+date: 2022-06-15
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.3  = Replaced by the version number (eg: v1.2)
-    June 15, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.3">https://github.com/matrix-org/matrix-spec/tree/v1.3</a></td>
-<tr><th>Release date</th><td>June 15, 2022</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.3" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.4.md

@@ -2,26 +2,13 @@
 title: v1.4 Changelog
 linkTitle: v1.4
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-09-29T00:00:00+0100
+date: 2022-09-29
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.4  = Replaced by the version number (eg: v1.2)
-    September 29, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.4">https://github.com/matrix-org/matrix-spec/tree/v1.4</a></td>
-<tr><th>Release date</th><td>September 29, 2022</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.4" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.5.md

@@ -2,26 +2,13 @@
 title: v1.5 Changelog
 linkTitle: v1.5
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-11-17T08:22:11-07:00
+date: 2022-11-17
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.5  = Replaced by the version number (eg: v1.2)
-    November 17, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.5">https://github.com/matrix-org/matrix-spec/tree/v1.5</a></td>
-<tr><th>Release date</th><td>November 17, 2022</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.5" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.6.md

@@ -2,26 +2,13 @@
 title: v1.6 Changelog
 linkTitle: v1.6
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-02-14T08:25:40-07:00
+date: 2023-02-14
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.6  = Replaced by the version number (eg: v1.2)
-    February 14, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.6">https://github.com/matrix-org/matrix-spec/tree/v1.6</a></td>
-<tr><th>Release date</th><td>February 14, 2023</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.6" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.7.md

@@ -2,26 +2,13 @@
 title: v1.7 Changelog
 linkTitle: v1.7
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-05-25T09:47:21-06:00
+date: 2023-05-25
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.7  = Replaced by the version number (eg: v1.2)
-    May 25, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.7">https://github.com/matrix-org/matrix-spec/tree/v1.7</a></td>
-<tr><th>Release date</th><td>May 25, 2023</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.7" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.8.md

@@ -2,26 +2,12 @@
 title: v1.8 Changelog
 linkTitle: v1.8
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-08-23T09:23:53-06:00
+date: 2023-08-23
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.8  = Replaced by the version number (eg: v1.2)
-    August 23, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.8">https://github.com/matrix-org/matrix-spec/tree/v1.8</a></td>
-<tr><th>Release date</th><td>August 23, 2023</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.8" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.9.md

@@ -2,26 +2,12 @@
 title: v1.9 Changelog
 linkTitle: v1.9
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-11-29T10:04:26-07:00
+date: 2023-11-29
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.9  = Replaced by the version number (eg: v1.2)
-    November 29, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.9">https://github.com/matrix-org/matrix-spec/tree/v1.9</a></td>
-<tr><th>Release date</th><td>November 29, 2023</td>
-<tr><th>Checklist</th><td><a href="{{< relref path="changelog/v1.9" outputFormat="Checklist" >}}">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

layouts/_default/single.checklist.md

@@ -1,4 +0,0 @@
-{{ .RawContent
-    | replaceRE "\n- " "\n- [ ] "
-    | replaceRE "<!--(.|\\s)*?-->\n?" ""
-    | replaceRE "<tr><th>Checklist.*\n" "" }}

layouts/docs/changelog.checklist.md

@@ -0,0 +1,34 @@
+{{- /*
+
+    Template to render a page with a `changelog` layout as a markdown checklist.
+
+    This transforms the markdown source of the changelog to change list items,
+    which in turn are them transformed into a rendered checklist.
+
+    Stable releases will additionally have a table at the top of the page with
+    information about the release, including:
+
+    * A link to the matrix-spec repository at the time of the release, with the
+      version taken from the `linkTitle` in the frontmatter of the page.
+    * The date of the release, taken from the `date` in the frontmatter of the
+      page.
+
+*/ -}}
+
+{{ $version := lower .LinkTitle -}}
+# Matrix Specification {{ .Title }}
+
+{{ if ne $version "unstable" -}}
+{{- /*
+
+    Most markdown parsers require the header to recognize a markdown table,
+    so add an empty header.
+
+*/ -}}
+|   |   | 
+|---|---|
+| Git commit | {{ printf "https://github.com/matrix-org/matrix-spec/tree/%s" $version }} |
+| Release date | {{ .Date | time.Format ":date_long" }} |
+{{ end -}}
+
+{{ .RawContent | replaceRE "\n- " "\n- [ ] " }}

layouts/docs/changelog.html

@@ -0,0 +1,46 @@
+{{- /*
+
+    Template to render a page with a `changelog` layout or the `changelog`
+    section page. This conflation seems to be a limitation of Hugo currently, it
+    uses this template for both cases.
+
+    For the `changelog` section page, this redirects the page to the latest
+    version's changelog page.
+
+    For a page with a `changelog` layout, this adds a table at the top of the
+    page with information about the release:
+
+    * A link to the matrix-spec repository at the time of the release, with the
+      version taken from the `linkTitle` in the frontmatter of the page, unless
+      it is the unstable changelog.
+    * The date of the release, taken from the `date` in the frontmatter of the
+      page, unless it is the unstable changelog.
+    * A link to the markdown checklist format of the changelog. The `outputs` in
+      the frontmatter of the page must include `checklist`.
+
+*/ -}}
+
+{{ define "main" }}
+{{ if .IsSection -}}
+    {{ with index .RegularPages.ByDate.Reverse 0 -}}
+    <meta http-equiv="refresh" content="0; url={{ .RelPermalink }}">
+    {{ end -}}
+{{ else -}}
+    {{ $version := lower .LinkTitle -}}
+<div class="td-content">
+    <h1>{{ .Title }}</h1>
+
+    <table class="release-info">
+        {{ if ne $version "unstable" -}}
+            {{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $version -}}
+        <tr><th>Git commit</th><td><a href="{{ $commitLink }}">{{ $commitLink }}</a></td>
+        <tr><th>Release date</th><td>{{ .Date | time.Format ":date_long" }}</td>
+        {{ end -}}
+        {{ $checklist := .OutputFormats.Get "checklist" -}}
+        <tr><th>Checklist</th><td><a href="{{ $checklist.RelPermalink }}">checklist.md</a></td>
+    </table>
+
+    {{ .Content }}
+</div>
+{{ end -}}
+{{ end }}

layouts/shortcodes/changelog/changelogs.html

@@ -1,8 +0,0 @@
-{{/*
-   This template is used to redirect the changelog section under
-   "content/changelogs" to the latest version's changelog page.
-*/}}
-
-{{ with index .Page.RegularPages.ByDate.Reverse 0 }}
-   <meta http-equiv="refresh" content="0; url={{ .RelPermalink }}">
-{{ end }}

meta/releasing.md

@@ -79,8 +79,9 @@ release.
 3. Commit the changes.
 4. Generate the changelog.
    1. Activate your python virtual environment.
-   2. Run `./scripts/generate-changelog.sh v1.2 "October 01, 2021"` (using the correct
+   2. Run `./scripts/generate-changelog.sh v1.2` (using the correct version number).
-      version number and same `release_date` format from the hugo config).
+      The script will use the current date. If that date is wrong, correct the document
+      by using the same `YYYY-MM-DD` date format.
    3. Commit the result.
 5. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2).
 6. Push the release branch and the tag.

scripts/generate-changelog.sh

@@ -1,20 +1,16 @@
 # /bin/bash
 
-# Usage: ./scripts/generate-changelog.sh v1.2 "April 01, 2021"
+# Usage: ./scripts/generate-changelog.sh v1.2 for changelogs of stable releases
-# or: ./scripts/generate-changelog.sh vUNSTABLE
+# or: ./scripts/generate-changelog.sh vUNSTABLE for the unstable changelog.
 
 set -e
 
 VERSION="$1"
-DATE="$2"
 
-cd `dirname $0`/../changelogs
+if [ -z "$VERSION" ]; then
-
+    echo "ERROR: The version of the changelog must be provided"
-# Pre-cleanup just in case it wasn't done on the last run
+    exit 1
-rm -f rendered.md
+fi
-
-# Generate changelog
-towncrier --yes
 
 if [ "$VERSION" = "vUNSTABLE" ]; then
     TITLE="Changes since last release"
@@ -26,6 +22,14 @@ else
     FILENAME="$VERSION.md"
 fi
 
+cd `dirname $0`/../changelogs
+
+# Pre-cleanup just in case it wasn't done on the last run
+rm -f rendered.md
+
+# Generate changelog
+towncrier --yes
+
 {
     # Prepare the header
     # We include the generation date in the front matter so that we can use it
@@ -35,16 +39,13 @@ fi
 title: $TITLE
 linkTitle: $LINKTITLE
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: $(date -Iseconds)
+date: $(date -Idate)
 ---
 EOF
-    if [ "$VERSION" != "vUNSTABLE" ]; then
-        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 -e "s/[ ]*$//" rendered.md
 } > ../content/changelog/$FILENAME