add changelog builder for release publishing (#1377)

## Summary
Add changelog builder to the publishing workflow. This allows us to
provide richer release information to users.

## Details
The changelog builder will tally all PRs merged between the previous tag
and the latest tag, then generate a categorized changelog for them. The
configuration for the builder can be found at  `.github/changelog.json`
.

In addition to this,  `/generate-changelog`  PR command has been added,
which allows maintainers to generate a changelog based on the new
configuration within a given PR.

Usage:

/generate-changelog [from=<tag>] [to=<tag>] [no_prerelease=<true|false>]

Where:

-  `from` : Specify the previous tag. If not provided, will be the first
tag older than  `to` .
-  `to` : Specify the latest tag. If not provided, will be the latest
tag in this repository.
-  `no_prerelease` : Only applies when  `from`  is not provided. If set
to  `true` ,  `from`  is selected such that the older tag is /not/ a
pre-release. Defaults to  `false` .

.github/changelog.json

@@ -0,0 +1,90 @@
+{
+  "categories": [
+    {
+      "title": "## 🚀 Features",
+      "labels": ["enhancement"],
+      "categories": [
+        {
+          "title": "### Compiler",
+          "labels": ["enhancement"],
+          "exhaustive": true,
+          "rules": [
+            {
+              "on_property": "labels",
+              "pattern": "compiler.*"
+            }
+          ]
+        },
+        {
+          "title": "### Standard Library",
+          "labels": ["enhancement", "stdlib"],
+          "exhaustive": true
+        },
+        {
+          "title": "### Tooling",
+          "labels": ["enhancement", "tools"],
+          "exhaustive": true
+        }
+      ]
+    },
+    {
+      "title": "## 🐛 Fixes",
+      "labels": ["bug"],
+      "categories": [
+        {
+          "title": "### Compiler",
+          "labels": ["bug"],
+          "exhaustive": true,
+          "rules": [
+            {
+              "on_property": "labels",
+              "pattern": "compiler.*"
+            }
+          ]
+        },
+        {
+          "title": "### Standard Library",
+          "labels": ["bug", "stdlib"],
+          "exhaustive": true
+        },
+        {
+          "title": "### Tooling",
+          "labels": ["bug", "tool"],
+          "exhaustive": true
+        }
+      ]
+    },
+    {
+      "title": "## 🔧 Refactorings",
+      "labels": ["refactor", "simplification"],
+      "categories": [
+        {
+          "title": "### Compiler",
+          "labels": ["refactor", "simplification"],
+          "exhaustive_rules": true,
+          "rules": [
+            {
+              "on_property": "labels",
+              "pattern": "compiler.*"
+            }
+          ]
+        },
+        {
+          "title": "### Standard Library",
+          "labels": ["refactor", "stdlib"],
+          "exhaustive": true
+        },
+        {
+          "title": "### Tooling",
+          "labels": ["refactor", "tool"],
+          "exhaustive": true
+        }
+      ]
+    }
+  ],
+  "template": "# What's Changed\n\n#{{CHANGELOG}}\n\n<details>\n<summary>\n\n## 💬 Other\n\n</summary>\n\n#{{UNCATEGORIZED}}\n\n</details>\n\n**Full Changelog**: #{{RELEASE_DIFF}}",
+  "empty_template": "**Full Changelog**: #{{RELEASE_DIFF}}",
+  "pr_template": "* #{{TITLE}} by @#{{AUTHOR}} in #{{URL}}",
+  "sort": "DSC",
+  "base_branches": ["devel"]
+}

.github/workflows/publisher.yml

@@ -25,6 +25,13 @@ jobs:
       url: ${{ steps.release.outputs.url }}
 
     steps:
+      # Repository required for changelog builder
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          sparse-checkout: |
+            .github
+
       - name: Obtain latest successful run id
         id: finder
         run: |
@@ -103,5 +110,17 @@ jobs:
           tag_name: ${{ steps.release-files.outputs.version }}
           fail_on_unmatched_files: true
           target_commitish: ${{ github.event.after }}
-          body: |
-            Continuous delivery for commit ${{ github.event.after }}
+
+      - id: changelog
+        name: Create release changelog
+        uses: mikepenz/[email protected]
+        with:
+          configuration: ".github/changelog.json"
+          toTag: ${{ steps.release-files.outputs.version }}
+          failOnError: true
+
+      - name: Push changelog
+        uses: softprops/[email protected]
+        with:
+          tag_name: ${{ steps.release-files.outputs.version }}
+          body: ${{ steps.changelog.outputs.changelog }}

.github/workflows/slash-command-generate-changelog.yml

@@ -0,0 +1,81 @@
+name: /generate-changelog handler
+
+on:
+  repository_dispatch:
+    types: [generate-changelog-command]
+
+permissions:
+  pull-requests: write
+
+concurrency: generate-changelog-handler-${{ github.event.client_payload.pull_request.node_id || github.run_id }}
+
+jobs:
+  changelog:
+    if: github.event.client_payload.pull_request != null
+    name: Generate changelog and comment
+
+    runs-on: ubuntu-latest
+    env:
+      PR: ${{ github.event.client_payload.pull_request.number }}
+    steps:
+      - if: github.event.client_payload.pull_request.merge_commit_sha == null
+        name: Report "No merge HEAD" found
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{ env.PR }}
+          body: |
+            Could not generate changelog using this PR as no GitHub merge commits are available.
+
+            This could be due to the PR being recently opened or there is a merge conflict. Please
+            try again after a few minutes.
+
+      - if: github.event.client_payload.pull_request.merge_commit_sha == null
+        name: Fail due to "No merge HEAD"
+        run: |
+          echo "::error::No merge HEAD found for PR #$PR"
+          exit 1
+
+      - name: "Checkout merge head for #${{ env.PR }}"
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.client_payload.pull_request.merge_commit_sha }}
+          sparse-checkout: |
+            .github
+
+      - id: changelog
+        name: Create changelog
+        uses: mikepenz/[email protected]
+        with:
+          configuration: ".github/changelog.json"
+          fromTag: ${{ github.event.client_payload.slash_command.args.named.from || '' }}
+          toTag: ${{ github.event.client_payload.slash_command.args.named.to || '' }}
+          ignorePreReleases: ${{ github.event.client_payload.slash_command.args.named.no_prerelease || false }}
+
+      - if: steps.changelog.outputs.failed == 'true'
+        name: Report failure
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{ env.PR }}
+          body: |
+            Error occurred while generating changelog using this PR.
+
+            See run log at ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}.
+
+      - if: steps.changelog.outputs.failed == 'true'
+        name: Fail due to changelog
+        run: |
+          echo "::error::Error occurred while generating changelog using PR #$PR"
+          exit 1
+
+      - name: Comment with changelog
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{ env.PR }}
+          body: |
+            Changelog requested by: @${{ github.event.client_payload.github.payload.comment.user.login }}
+
+            Generated between ${{ steps.changelog.outputs.fromTag }} to ${{ steps.changelog.outputs.toTag }} using configuration provided by this PR.
+
+            ---
+
+            ${{ steps.changelog.outputs.changelog }}

.github/workflows/slash-commands.yml

@@ -23,5 +23,6 @@ jobs:
           reaction-token: ${{ steps.token.outputs.token }}
           commands: |
             merge
+            generate-changelog
           issue-type: pull-request
           permission: write