[CICD-73] Automate population of GitHub release notes (#41)

* Create action to retrieve release notes

* Add output to report whether new tag was published

* Split versioning and releasing to separate jobs

* Add steps to create GitHub release

* Update release documentation

Author: apmatthews

.github/actions/get-release-notes/action.yml

@@ -0,0 +1,24 @@
+name: Get release notes
+description: Retrieves the release notes for a given version from the changelog.
+inputs:
+  version:
+    description: "Which version's release notes to retrieve."
+    required: true
+  changelog:
+    description: "Path to the changelog."
+    required: true
+outputs:
+  release_notes:
+    description: "Release notes parsed from the changelog."
+    value: ${{ steps.notes.outputs.RELEASE_NOTES }}
+runs:
+  using: 'composite'
+  steps:
+    - id: notes
+      run: |
+          notes=$(node ${{ github.action_path }}/getReleaseNotes ${{ inputs.version }} ${{ inputs.changelog }})
+          notes="${notes//'%'/'%25'}"
+          notes="${notes//$'\n'/'%0A'}"
+          notes="${notes//$'\r'/'%0D'}"
+          echo "::set-output name=RELEASE_NOTES::$notes"
+      shell: bash

.github/actions/get-release-notes/getReleaseNotes.js

@@ -0,0 +1,74 @@
+#! /usr/bin/env node
+
+const [,, ...args] = process.argv;
+
+const fs = require('fs/promises');
+const path = require("path");
+
+const readFile = (filename) => fs.readFile(filename, { encoding: "utf8" });
+
+(async ()=>{
+    if (! args[0] || ! args[1] ) {
+        printUsageInstructions();
+        process.exit(1);
+    }
+
+    const notes = await getReleaseNotes(args[0], args[1]);
+
+    process.stdout.write(notes);
+})();
+
+/**
+ * Retrieves the changelog entry for a particular version.
+ * 
+ * Expects the changelog to be a markdown file as generated by Changesets.
+ *
+ * @param {String} version       The version number to get notes for.
+ * @param {String} changelogPath Path to the CHANGELOG.md file.
+ */
+async function getReleaseNotes(version, changelogPath) {
+    changelogPath = path.resolve(changelogPath);
+
+    let changelog = await readFile(changelogPath);
+
+    const versionStart = changelog.indexOf(`## ${version}`);
+
+    if ( versionStart < 0 ) {
+        throw new Error(`Version ${version} does not exist in ${changelogPath}`);
+    }
+
+    changelog = changelog.substring( versionStart );
+
+    // split the contents by new line
+    const changelogLines = changelog.split(/\r?\n/);
+    // we don't need the version heading in release notes, so drop the first line
+    changelogLines.shift();
+    const processedLines = [];
+
+    // print all lines in current version
+    changelogLines.every((line) => {
+      // Version numbers in CHANGELOG.md are h2, so we've hit the next version
+      if (line.startsWith("## ")) {
+          return false;
+      }
+
+      if (line.startsWith("### ")) {
+        // Make h3 into h2
+        line = line.replace("### ", "## ");
+      }
+
+      processedLines.push(line);
+
+      return true;
+    });
+
+    return processedLines.join("\n");
+}
+
+function printUsageInstructions() {
+    usage =  "Usage: node getReleaseNotes <version> <changelogPath>\n";
+    usage += "\n";
+    usage += "Example use:\n";
+    usage += "  node getReleaseNotes 3.0.1 ../CHANGELOG.md\n";
+    console.info(usage);
+}

.github/actions/publish/action.yml

@@ -4,8 +4,13 @@ inputs:
   version:
     description: 'Patch version to publish.'
     required: true
+outputs:
+  published:
+    description: 'Whether a new version was published.'
+    value: ${{ steps.publish.outputs.PUBLISHED }}
 runs:
   using: 'composite'
   steps:
-    - run: "${{ github.action_path }}/publish.sh ${{ inputs.version }}"
+    - id: publish
+      run: "${{ github.action_path }}/publish.sh ${{ inputs.version }}"
       shell: bash

.github/actions/publish/publish.sh

@@ -23,6 +23,7 @@ version="$1"
 #   capture 4: patch number with dot
 #   capture 5: patch number without dot
 VERSION_REGEX="^([1-9][0-9]*)(\.(0|[1-9][0-9]*)){0,1}(\.(0|[1-9][0-9]*)){0,1}$"
+PUBLISHED='false'
 
 if [[ "$version" =~ $VERSION_REGEX ]] ; then
     majorTag="v${BASH_REMATCH[1]}"
@@ -41,6 +42,7 @@ else
     echo "Creating tag: $patchTag"
     git tag -a "$patchTag" -m " Release $patchTag"
     git push origin "$patchTag"
+    PUBLISHED='true'
 fi
 
 for tag in "${tagsToUpdate[@]}"; do
@@ -55,4 +57,6 @@ for tag in "${tagsToUpdate[@]}"; do
 
     git tag -fa "$tag" -m "$message"
     git push origin "$tag" --force
-done
+done
+
+echo "::set-output name=PUBLISHED::$PUBLISHED"

.github/workflows/release.yml

@@ -8,14 +8,15 @@ on:
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
-  release:
-    name: Version and Release
+  versioning:
+    name: Versioning
     runs-on: ubuntu-latest
+    outputs:
+      hasChangesets: ${{ steps.changesets.outputs.hasChangesets }}
+      version: ${{ steps.version.outputs.CURRENT_VERSION }}
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
 
       - name: Setup Node.js 16.x
         uses: actions/setup-node@v2
@@ -38,8 +39,44 @@ jobs:
         id: version
         run: echo "::set-output name=CURRENT_VERSION::$(node -p "require('./package.json').version")"
 
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: versioning
+    if: needs.versioning.outputs.hasChangesets == 'false'
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - name: Setup Node.js 16.x
+        uses: actions/setup-node@v2
+        with:
+          node-version: 16.x
+
       - name: Publish tags
-        if: steps.changesets.outputs.hasChangesets == 'false'
+        id: publish
         uses: ./.github/actions/publish
         with:
-          version: ${{ steps.version.outputs.CURRENT_VERSION }}
+          version: ${{ needs.versioning.outputs.version }}
+
+      - name: Get release notes
+        id: notes
+        if: steps.publish.outputs.published == 'true'
+        uses: ./.github/actions/get-release-notes
+        with:
+          version: ${{ needs.versioning.outputs.version }}
+          changelog: ./CHANGELOG.md
+
+      - name: Create release
+        if: steps.notes.outputs.release_notes
+        uses: softprops/action-gh-release@1e07f4398721186383de40550babbdf2b84acfc5
+        with:
+          body: ${{ steps.notes.outputs.release_notes }}
+          tag_name: v${{ needs.versioning.outputs.version }}

DEVELOPMENT.md

@@ -26,11 +26,4 @@ We use [Changesets](https://github.com/changesets/changesets) to automate versio
     - [ ] All `.changeset/*.md` files were removed.
 3. Approve, then "Squash and merge" the PR into `main`.
 
-Merging the versioning PR will run a workflow that creates or updates all necessary tags. The next step is to create a release in GitHub. This may be automated in the future, but for now the process is:
-
-1. In GitHub, visit "Releases -> Draft new release"
-2. In the "Choose a tag" dropdown, choose the tag you want to release. This is usually the most recently created patch tag (`v{MAJOR}.{MINOR}.{PATCH}`). Major/minor tags (i.e `v3` and `v3.0`) are only present to allow users to opt into automatic patch or minor version updates and should not be associated with a GitHub release.
-3. Leave the target branch set to `main`.
-4. Give the release a title. Typically, this will be identical to the release's tag name.
-5. Copy the [CHANGLELOG.md](./CHANGELOG.md) entry for this release into the release body.
-6. Click "Publish Release".
+Merging the versioning PR will run a workflow that creates or updates all necessary tags. It will also create a new release in GitHub.