wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Kévin Commaille 2024-12-23 18:46:52 +01:00 • committed by GitHub
parent baa60bf728
commit 6f1e64cb12
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 127 additions and 246 deletions
Download patch file Download diff file Expand all files Collapse all files

15
changelogs/header.md
View file

@ -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 -->

1
changelogs/internal/newsfragments/2033.clarification Normal file
View file

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

2
content/changelog/_index.md
View file

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

17
content/changelog/v1.1.md
View file

@ -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

18
content/changelog/v1.10.md
View file

@ -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

18
content/changelog/v1.11.md
View file

@ -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

18
content/changelog/v1.12.md
View file

@ -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

18
content/changelog/v1.13.md
View file

@ -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

17
content/changelog/v1.2.md
View file

@ -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

17
content/changelog/v1.3.md
View file

@ -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

17
content/changelog/v1.4.md
View file

@ -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

17
content/changelog/v1.5.md
View file

@ -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

17
content/changelog/v1.6.md
View file

@ -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

17
content/changelog/v1.7.md
View file

@ -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

18
content/changelog/v1.8.md
View file

@ -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

18
content/changelog/v1.9.md
View file

@ -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

4
layouts/_default/single.checklist.md
View file

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

34
layouts/docs/changelog.checklist.md Normal file
View file

@ -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- [ ] " }}

46
layouts/docs/changelog.html Normal file
View file

@ -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 }}

8
layouts/shortcodes/changelog/changelogs.html
View file

@ -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 }}

5
meta/releasing.md
View file

@ -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.

31
scripts/generate-changelog.sh
View file

@ -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