From ce84f1682ca5d2180354401add0fb04c6d4cea51 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 18:39:38 +0000 Subject: [PATCH 1/8] Use Hugo page resources instead of partials for changelogs ... which means we don't need to edit the top-level page for each release. --- content/{changelog.md => changelog/index.md} | 6 +----- .../partials/changelogs => content/changelog}/v1.1.md | 0 .../partials/changelogs => content/changelog}/v1.2.md | 0 .../partials/changelogs => content/changelog}/v1.3.md | 0 .../partials/changelogs => content/changelog}/v1.4.md | 0 layouts/partials/changelogs/.gitkeep | 0 layouts/shortcodes/changelog/changelog-rendered.html | 2 -- layouts/shortcodes/changelog/changelogs.html | 10 ++++++++++ scripts/generate-changelog.sh | 5 +---- 9 files changed, 12 insertions(+), 11 deletions(-) rename content/{changelog.md => changelog/index.md} (87%) rename {layouts/partials/changelogs => content/changelog}/v1.1.md (100%) rename {layouts/partials/changelogs => content/changelog}/v1.2.md (100%) rename {layouts/partials/changelogs => content/changelog}/v1.3.md (100%) rename {layouts/partials/changelogs => content/changelog}/v1.4.md (100%) delete mode 100644 layouts/partials/changelogs/.gitkeep delete mode 100644 layouts/shortcodes/changelog/changelog-rendered.html create mode 100644 layouts/shortcodes/changelog/changelogs.html mode change 100644 => 100755 scripts/generate-changelog.sh diff --git a/content/changelog.md b/content/changelog/index.md similarity index 87% rename from content/changelog.md rename to content/changelog/index.md index a84514b61..d329ad6f4 100644 --- a/content/changelog.md +++ b/content/changelog/index.md @@ -8,11 +8,7 @@ weight: 1000 {{% changelog/changelog-changes %}} - -{{% changelog/changelog-rendered p="changelogs/v1.4.md" %}} -{{% changelog/changelog-rendered p="changelogs/v1.3.md" %}} -{{% changelog/changelog-rendered p="changelogs/v1.2.md" %}} -{{% changelog/changelog-rendered p="changelogs/v1.1.md" %}} +{{% changelog/changelogs %}}

Historical versions

diff --git a/layouts/partials/changelogs/v1.1.md b/content/changelog/v1.1.md similarity index 100% rename from layouts/partials/changelogs/v1.1.md rename to content/changelog/v1.1.md diff --git a/layouts/partials/changelogs/v1.2.md b/content/changelog/v1.2.md similarity index 100% rename from layouts/partials/changelogs/v1.2.md rename to content/changelog/v1.2.md diff --git a/layouts/partials/changelogs/v1.3.md b/content/changelog/v1.3.md similarity index 100% rename from layouts/partials/changelogs/v1.3.md rename to content/changelog/v1.3.md diff --git a/layouts/partials/changelogs/v1.4.md b/content/changelog/v1.4.md similarity index 100% rename from layouts/partials/changelogs/v1.4.md rename to content/changelog/v1.4.md diff --git a/layouts/partials/changelogs/.gitkeep b/layouts/partials/changelogs/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/layouts/shortcodes/changelog/changelog-rendered.html b/layouts/shortcodes/changelog/changelog-rendered.html deleted file mode 100644 index bbfd6e533..000000000 --- a/layouts/shortcodes/changelog/changelog-rendered.html +++ /dev/null @@ -1,2 +0,0 @@ -{{ $partial := .Params.p }} -{{ partial $partial . }} diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html new file mode 100644 index 000000000..c4b781d1a --- /dev/null +++ b/layouts/shortcodes/changelog/changelogs.html @@ -0,0 +1,10 @@ +{{/* + This template is used to render all of the changelog sections under + "content/changelogs" +*/}} + +{{ with .Page.Resources.Match "*.md" }} +{{ range ((sort . "Name" "desc")) }} +{{ .Content }} +{{ end }} +{{ end }} diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh old mode 100644 new mode 100755 index f66e53585..8cc9ae792 --- a/scripts/generate-changelog.sh +++ b/scripts/generate-changelog.sh @@ -4,8 +4,6 @@ set -e -MAGIC_STRING="" - cd changelogs # Pre-cleanup just in case it wasn't done on the last run @@ -31,8 +29,7 @@ cat rendered.header.md rendered.md > rendered.final.md sed -i "s/[ ]*$//" rendered.final.md # Put the changelog in place -mv rendered.final.md ../layouts/partials/changelogs/$1.md -sed -i "s/$MAGIC_STRING/$MAGIC_STRING\n{{% changelog\\/changelog-rendered p=\"changelogs\\/$1.md\" %}}/" ../content/changelog.md +mv rendered.final.md ../content/changelogs/$1.md # Cleanup rm -v rendered.* From 92db0ee92ceb71946ab215df3e9c3ae2a88bb485 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 18:01:51 +0000 Subject: [PATCH 2/8] Generate unstable changelogs using towncrier --- .github/workflows/main.yml | 26 +++++- content/changelog/index.md | 2 - .../changelog/changelog-changes.html | 90 ------------------- scripts/generate-changelog.sh | 34 ++++--- 4 files changed, 44 insertions(+), 108 deletions(-) delete mode 100644 layouts/shortcodes/changelog/changelog-changes.html diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ce54f976b..70b69fb28 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/content/changelog/index.md b/content/changelog/index.md index d329ad6f4..560cb43b0 100644 --- a/content/changelog/index.md +++ b/content/changelog/index.md @@ -6,8 +6,6 @@ weight: 1000 {{% changelog/changelog-description %}} -{{% changelog/changelog-changes %}} - {{% changelog/changelogs %}}

Historical versions

diff --git a/layouts/shortcodes/changelog/changelog-changes.html b/layouts/shortcodes/changelog/changelog-changes.html deleted file mode 100644 index 99efce085..000000000 --- a/layouts/shortcodes/changelog/changelog-changes.html +++ /dev/null @@ -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.`; 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" }} - - - -
Git commithttps://github.com/matrix-org/matrix-spec/tree/{{ $release_tag }}
Release date{{ .Site.Params.version.release_date }}
-{{ end }} - -

Changes since last release

-{{ 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" }} -

{{ .title }}

- {{ $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 }} - -
    -{{ range $config.tool.towncrier.type }} - {{ $changes_of_type := (index $types .directory) }} - {{ if $changes_of_type }} -
  • {{.name | safeHTML}} -

      - {{ range $changes_of_type }} -
    • {{ .ticket }}: {{ .description | markdownify }}
      • - {{ end }} -

    -
    • - {{ end }} -{{ end }} -
-{{ end }} diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh index 8cc9ae792..25fe8c9d1 100755 --- a/scripts/generate-changelog.sh +++ b/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 - -# Remove trailing whitespace (such as our intentionally blank RST headings) -sed -i "s/[ ]*$//" rendered.final.md +{ + # Prepare the header + if [ "$VERSION" = "vUNSTABLE" ]; then + cat < ../content/changelog/$VERSION.md # Cleanup -rm -v rendered.* +rm -v rendered.md From 7a20fd8f735c4caab4523aad8633f2d7e6c208bf Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 19:14:02 +0000 Subject: [PATCH 3/8] skip changelog on tags --- .github/workflows/main.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 70b69fb28..e8abc2421 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -101,6 +101,8 @@ jobs: generate-changelog: name: "📢 Run towncrier for changelog" + # skip for builds of git tags + if: "!startsWith(github.ref, 'refs/tags/')" runs-on: ubuntu-latest steps: - name: "📥 Source checkout" @@ -138,6 +140,7 @@ jobs: npm i npm run get-proposals - name: "📥 Download generated changelog" + if: "needs.generate-changelog.result == 'success'" uses: actions/download-artifact@v3 with: name: changelog-artifact From b3912bd21b2c1dbd9690eb3f1f5b88a75f48cfaa Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 19:33:05 +0000 Subject: [PATCH 4/8] update release doc --- meta/releasing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/meta/releasing.md b/meta/releasing.md index 3e01dc862..7483c357b 100644 --- a/meta/releasing.md +++ b/meta/releasing.md @@ -37,21 +37,21 @@ release. release_date = "October 01, 2021" ``` 3. Commit the changes. -4. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2). -5. Push the release branch and the tag. -6. GitHub Actions will run its build steps. Wait until these are successful. If fixes - need to be made to repair the pipeline or spec build, delete and re-tag the release. -7. Check out and fast-forward `main` to the release branch. -8. Generate the changelog. This is done *after* the tagging to ensure the rendered - changelog makes sense. +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). 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. +7. GitHub Actions will run its build steps. Wait until these are successful. If fixes + need to be made to repair the pipeline or spec build, delete and re-tag the release. + You may need to fix up the changelog file by hand in this case. +8. Check out and fast-forward `main` to the release branch. 9. Create a new release on GitHub from the newly created tag. * The title should be just "v1.2" (for example). * The description should be a copy/paste of the changelog. The generated changelog - will be at `content/partials/changelogs/v1.2.md` - copy/paste verbatim. + will be at `content/changelog/v1.2.md` - copy/paste verbatim. * Upload the artifacts of the GitHub Actions build for the release to the GitHub release as artifacts themselves. This should be the tarball that will be deployed to spec.matrix.org. From 1203ebeb38cc79e72488bc3108f9a64c7e4b1627 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 18:03:16 +0000 Subject: [PATCH 5/8] changelog --- changelogs/internal/newsfragments/1340.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/internal/newsfragments/1340.clarification diff --git a/changelogs/internal/newsfragments/1340.clarification b/changelogs/internal/newsfragments/1340.clarification new file mode 100644 index 000000000..a31804403 --- /dev/null +++ b/changelogs/internal/newsfragments/1340.clarification @@ -0,0 +1 @@ +Generate the unstable changelogs with towncrier, for consistency. From 78a673718f6b6d5731f6c0cb7a171f69db94d599 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 22:43:43 +0000 Subject: [PATCH 6/8] Fix build for tagged versions Make sure we don't skip building the spec! --- .github/workflows/main.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index e8abc2421..a77191d6b 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -123,6 +123,8 @@ jobs: name: "📖 Build the spec" runs-on: ubuntu-latest needs: [calculate-baseurl, build-openapi, generate-changelog] + # run even if generate-changelog was skipped + if: ${{ always() }} steps: - name: "➕ Setup Node" uses: actions/setup-node@v2 From 46596d750a55e5f606f4bcd6d47c696ed8caf0ba Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Nov 2022 23:03:38 +0000 Subject: [PATCH 7/8] Sort changelogs by release date --- content/changelog/v1.1.md | 3 +++ content/changelog/v1.2.md | 3 +++ content/changelog/v1.3.md | 3 +++ content/changelog/v1.4.md | 3 +++ layouts/shortcodes/changelog/changelogs.html | 2 +- scripts/generate-changelog.sh | 11 ++++++++--- 6 files changed, 21 insertions(+), 4 deletions(-) diff --git a/content/changelog/v1.1.md b/content/changelog/v1.1.md index b8e0832d7..48934fb3c 100644 --- a/content/changelog/v1.1.md +++ b/content/changelog/v1.1.md @@ -1,3 +1,6 @@ +--- +date: 1636416000 +---