Check out the HEAD of the release branch for tag events (#898)

* Check out the HEAD of the release branch for tag events

Tags aren't necessarily made to the HEAD of the version branch.
The documentation to be published is always on the HEAD of the release branch.

Because the workflow now uses regular expressions in Bash, inputs must now use Extended Regular Expression syntax.

Signed-off-by: Jack Baldry <[email protected]>

* Document how to release GitHub Actions

Signed-off-by: Jack Baldry <[email protected]>

* Fix typo

---------

Signed-off-by: Jack Baldry <[email protected]>

RELEASE.md

@@ -0,0 +1,47 @@
+# Releases
+
+The Writers' Toolkit repository is a collection of different tools that can have different release mechanisms.
+
+## GitHub Actions
+
+The following directories contain GitHub Actions actions:
+
+- [`add-to-docs-project`](./add-to-docs-project/)
+- [`prettier`](./prettier/)
+- [`publish-technical-documentation`](./publish-technical-documentation/)
+- [`publish-technical-documentation-release`](./publish-technical-documentation-release/)
+
+You release each action by creating or updating Git tags.
+The Git tag begins with the action directory, then a slash (`/`), and then the tag version.
+For example, `publish-technical-documentation-release/v1.0.0` is the v1.0.0 release of the `publish-technical-documentation-release` action.
+
+The actions follow [semantic versioning](https://semver.org/).
+
+To create a tag, use the following command:
+
+```console
+git tag --annotate --force --sign --local-user=<GPG KEY ID> -m <MESSAGE> <TAG>
+```
+
+Where:
+
+- _`<GPG KEY ID>`_ is the ID of the GPG key associated with your GitHub account.
+
+  For more information refer to [Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+- _`<MESSAGE>`_ is a short message explaining the change to the action.
+
+  This is typically similar to a commit title explaining the "what" of the change.
+
+- _`TAG`_ is the name of the tag using the previously explained naming convention.
+
+Each release has three tags:
+
+- Major version: `<ACTION>/v<MAJOR>`
+- Major and minor version: `<ACTION>/v<MAJOR>.<MINOR>`
+- Major, minor, and patch version: `<ACTION>/v<MAJOR>.<MINOR>.<PATCH>`
+
+The major version tag should point to the same commit as the latest major and minor version tag.
+The major and minor version tag should point to the same commit as the major, minor, and patch version tag.
+
+The `--force` flag provided to the `git tag` command overwrites existing tags which you need to be able to move the major version and major and minor version tags when you release a new major, minor, and patch version.

publish-technical-documentation-release/action.yaml

@@ -102,6 +102,25 @@ runs:
       with:
         ref_name: ${{ github.ref_name }}
 
+    - name: Switch to HEAD of version branch for tags
+      # Tags aren't necessarily made to the HEAD of the version branch.
+      # The documentation to be published is always on the HEAD of the release branch.
+      if: steps.has-matching-release-tag.outputs.bool == 'true' && github.ref_type == 'tag'
+      env:
+        GITHUB_REF: ${{ github.ref }}
+        RELEASE_BRANCH_REGEXP: ${{ inputs.release_branch_regexp }}
+      run: |
+        branch="$(./publish-technical-documentation-release/determine-release-branch "${RELEASE_BRANCH_REGEXP}" "${GITHUB_REF}")"
+
+        if [[ -z "${branch}" ]]; then
+          echo "No release branch found for tag ${GITHUB_REF} matching ${RELEASE_BRANCH_REGEXP}. Exiting."
+
+          exit 1
+        fi
+
+        git switch --detach "origin/${branch}"
+      shell: bash
+
     - name: Sync to the website repository (release)
       if: steps.has-matching-release-tag.outputs.bool == 'true'
       uses: ./.github/actions/website-sync

publish-technical-documentation-release/determine-release-branch

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+set -euf -o pipefail
+
+function usage {
+  cat <<EOF
+Return the first release branch matching the provided branch regular expression that contains the provided tag.
+
+Usage:
+  $0 <BRANCH REGEXP> <TAG>
+
+Examples:
+  $0 '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.x$' v11.3.1
+EOF
+}
+
+if [[ $# -ne 2 ]]; then
+  usage
+
+  exit 2
+fi
+
+BRANCH_REGEXP="$1"
+TAG="$2"
+
+for branch in $(git branch -a --contains "tags/${TAG}"); do
+  branch="${branch#remotes/origin/}";
+
+  if [[ "${branch}" =~ ${BRANCH_REGEXP} ]]; then
+    echo "${branch}";
+
+    exit 0;
+  fi;
+done
+
+exit 1