From 6f1e64cb1271189cfa6bc310564f35d895326671 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Mon, 23 Dec 2024 18:46:52 +0100 Subject: [PATCH] Generate changelog release info with Hugo rather than when generating changelog (#2033) --- changelogs/header.md | 15 ------ .../internal/newsfragments/2033.clarification | 1 + content/changelog/_index.md | 2 +- content/changelog/v1.1.md | 17 +------ content/changelog/v1.10.md | 18 +------- content/changelog/v1.11.md | 18 +------- content/changelog/v1.12.md | 18 +------- content/changelog/v1.13.md | 18 +------- content/changelog/v1.2.md | 17 +------ content/changelog/v1.3.md | 17 +------ content/changelog/v1.4.md | 17 +------ content/changelog/v1.5.md | 17 +------ content/changelog/v1.6.md | 17 +------ content/changelog/v1.7.md | 17 +------ content/changelog/v1.8.md | 18 +------- content/changelog/v1.9.md | 18 +------- layouts/_default/single.checklist.md | 4 -- layouts/docs/changelog.checklist.md | 34 ++++++++++++++ layouts/docs/changelog.html | 46 +++++++++++++++++++ layouts/shortcodes/changelog/changelogs.html | 8 ---- meta/releasing.md | 5 +- scripts/generate-changelog.sh | 31 +++++++------ 22 files changed, 127 insertions(+), 246 deletions(-) delete mode 100644 changelogs/header.md create mode 100644 changelogs/internal/newsfragments/2033.clarification delete mode 100644 layouts/_default/single.checklist.md create mode 100644 layouts/docs/changelog.checklist.md create mode 100644 layouts/docs/changelog.html delete mode 100644 layouts/shortcodes/changelog/changelogs.html diff --git a/changelogs/header.md b/changelogs/header.md deleted file mode 100644 index 21f3b4d27..000000000 --- a/changelogs/header.md +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/VERSION
Release dateDATE
Checklist}}">checklist.md
- - diff --git a/changelogs/internal/newsfragments/2033.clarification b/changelogs/internal/newsfragments/2033.clarification new file mode 100644 index 000000000..9d3e75967 --- /dev/null +++ b/changelogs/internal/newsfragments/2033.clarification @@ -0,0 +1 @@ +Generate the changelog release info with Hugo, rather than the changelog generation script. diff --git a/content/changelog/_index.md b/content/changelog/_index.md index ccb55f6fd..c1c55f6ce 100644 --- a/content/changelog/_index.md +++ b/content/changelog/_index.md @@ -4,4 +4,4 @@ type: docs weight: 1000 --- -{{% changelog/changelogs %}} + diff --git a/content/changelog/v1.1.md b/content/changelog/v1.1.md index 7e31122dd..acfc1b218 100644 --- a/content/changelog/v1.1.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.1
Release dateNovember 09, 2021
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.10.md b/content/changelog/v1.10.md index 8a0e496d1..a3115a1f9 100644 --- a/content/changelog/v1.10.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.10
Release dateMarch 22, 2024
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.11.md b/content/changelog/v1.11.md index d38d874bc..7f12c1e35 100644 --- a/content/changelog/v1.11.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.11
Release dateJune 20, 2024
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.12.md b/content/changelog/v1.12.md index 8124ca28d..4f4f65dd9 100644 --- a/content/changelog/v1.12.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.12
Release dateOctober 07, 2024
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.13.md b/content/changelog/v1.13.md index ead58ee97..df91175b9 100644 --- a/content/changelog/v1.13.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.13
Release dateDecember 19, 2024
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.2.md b/content/changelog/v1.2.md index 224da53fd..9fd35eb57 100644 --- a/content/changelog/v1.2.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.2
Release dateFebruary 02, 2022
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.3.md b/content/changelog/v1.3.md index b8c99a7c1..270783e7a 100644 --- a/content/changelog/v1.3.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.3
Release dateJune 15, 2022
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.4.md b/content/changelog/v1.4.md index 10510d806..febb3874e 100644 --- a/content/changelog/v1.4.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.4
Release dateSeptember 29, 2022
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.5.md b/content/changelog/v1.5.md index 9f23a019b..71931cc77 100644 --- a/content/changelog/v1.5.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.5
Release dateNovember 17, 2022
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.6.md b/content/changelog/v1.6.md index d47c36b5a..f2a129c64 100644 --- a/content/changelog/v1.6.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.6
Release dateFebruary 14, 2023
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.7.md b/content/changelog/v1.7.md index f4b2b63e6..86f0b4ad7 100644 --- a/content/changelog/v1.7.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.7
Release dateMay 25, 2023
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.8.md b/content/changelog/v1.8.md index 1883d10ad..6e5cf9958 100644 --- a/content/changelog/v1.8.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.8
Release dateAugust 23, 2023
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/content/changelog/v1.9.md b/content/changelog/v1.9.md index a3971bd2a..9c38785d1 100644 --- a/content/changelog/v1.9.md +++ b/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 --- - - - - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.9
Release dateNovember 29, 2023
Checklist}}">checklist.md
- - ## Client-Server API diff --git a/layouts/_default/single.checklist.md b/layouts/_default/single.checklist.md deleted file mode 100644 index f885a3169..000000000 --- a/layouts/_default/single.checklist.md +++ /dev/null @@ -1,4 +0,0 @@ -{{ .RawContent - | replaceRE "\n- " "\n- [ ] " - | replaceRE "\n?" "" - | replaceRE "Checklist.*\n" "" }} diff --git a/layouts/docs/changelog.checklist.md b/layouts/docs/changelog.checklist.md new file mode 100644 index 000000000..17051c717 --- /dev/null +++ b/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- [ ] " }} diff --git a/layouts/docs/changelog.html b/layouts/docs/changelog.html new file mode 100644 index 000000000..b23c80748 --- /dev/null +++ b/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 -}} + + {{ end -}} +{{ else -}} + {{ $version := lower .LinkTitle -}} +
+

{{ .Title }}

+ + + {{ if ne $version "unstable" -}} + {{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $version -}} + + + {{ end -}} + {{ $checklist := .OutputFormats.Get "checklist" -}} + +
Git commit{{ $commitLink }}
Release date{{ .Date | time.Format ":date_long" }}
Checklistchecklist.md
+ + {{ .Content }} +
+{{ end -}} +{{ end }} diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html deleted file mode 100644 index d6c0add88..000000000 --- a/layouts/shortcodes/changelog/changelogs.html +++ /dev/null @@ -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 }} - -{{ end }} diff --git a/meta/releasing.md b/meta/releasing.md index 29de7d8fb..273e4eaad 100644 --- a/meta/releasing.md +++ b/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 - version number and same `release_date` format from the hugo config). + 2. Run `./scripts/generate-changelog.sh v1.2` (using the correct version number). + 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. diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh index 9447dac5a..678af60fb 100755 --- a/scripts/generate-changelog.sh +++ b/scripts/generate-changelog.sh @@ -1,20 +1,16 @@ # /bin/bash -# Usage: ./scripts/generate-changelog.sh v1.2 "April 01, 2021" -# or: ./scripts/generate-changelog.sh vUNSTABLE +# Usage: ./scripts/generate-changelog.sh v1.2 for changelogs of stable releases +# or: ./scripts/generate-changelog.sh vUNSTABLE for the unstable changelog. set -e VERSION="$1" -DATE="$2" -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 +if [ -z "$VERSION" ]; then + echo "ERROR: The version of the changelog must be provided" + exit 1 +fi 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