From 9108c14e4eb70ba768674f604eb29d4dab6d9442 Mon Sep 17 00:00:00 2001
From: Beth Griggs <bethanyngriggs@gmail.com>
Date: Mon, 19 Aug 2024 15:57:13 +0100
Subject: [PATCH] ci(release_workspace): add additional checks and document
 workflow

- Introduced logic to verify the branch name is valid for the workspace
- Added handling for missing GitHub events in release checks
- Introduced logic to set npm publish tag (latest or maintenance)
- Added initial plugin maintainer guide for patching older release lines

Signed-off-by: Beth Griggs <bethanyngriggs@gmail.com>
---
 .github/workflows/release_workspace.yml | 27 ++++++++++++++++---
 docs/plugin-maintainers-guide.md        | 36 +++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 4 deletions(-)
 create mode 100644 docs/plugin-maintainers-guide.md

diff --git a/.github/workflows/release_workspace.yml b/.github/workflows/release_workspace.yml
index d5f8439b52..59fc22fead 100644
--- a/.github/workflows/release_workspace.yml
+++ b/.github/workflows/release_workspace.yml
@@ -28,9 +28,9 @@ on:
         type: string
       branch:
         description: "Branch to run the workflow on"
-        required: false
-        default: "main"
+        required: true
         type: string
+        default: "main"
 
 concurrency:
   group: ${{ github.workflow }}-${{ inputs.workspace }}
@@ -74,6 +74,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Fetch previous commit for release check
+        if: ${{ github.event.before != '' }}
         run: git fetch origin '${{ github.event.before }}'
 
       - name: Fetch the commit that triggered the workflow (used by backstage/changesets-action)
@@ -85,6 +86,7 @@ jobs:
         if: inputs.force_release != true
         run: node ../../scripts/ci/check-if-release.js
         env:
+          TARGET_BRANCH: ${{ inputs.branch }}
           WORKSPACE_NAME: ${{ inputs.workspace }}
           COMMIT_SHA_BEFORE: '${{ github.event.before }}'
 
@@ -116,6 +118,14 @@ jobs:
       NODE_OPTIONS: --max-old-space-size=4096
 
     steps:
+      - name: Ensure branch name follows the 'workspace/{workspace}' pattern if not 'main'
+        run: |
+          if [ "${{ inputs.branch }}" != "main" ] && [[ "${{ inputs.branch }}" != "workspace/${{ inputs.workspace }}" ]]; then
+            echo "Branch name '${{ inputs.branch }}' does not follow the expected pattern 'workspace/${{ inputs.workspace }}'."
+            exit 1
+          fi
+        working-directory: ${{ github.workspace }}
+
       - name: Checkout
         uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4
         with:
@@ -150,13 +160,22 @@ jobs:
       - name: Build all packages
         run: yarn build:all
 
+      - name: Determine npm publish tag (latest or maintenance)
+        id: determine-tag
+        run: |
+          if [ "${{ inputs.branch }}" = "main" ]; then
+            echo "tag=latest" >> $GITHUB_OUTPUT
+          else
+            echo "tag=maintenance" >> $GITHUB_OUTPUT
+          fi
+
       - name: publish
         run: |
           yarn config set -H 'npmAuthToken' "${{secrets.NPM_TOKEN}}"
-          yarn workspaces foreach -v --no-private npm publish --access public --tolerate-republish
+          yarn workspaces foreach -v --no-private npm publish --access public --tolerate-republish --tag ${{ steps.determine-tag.outputs.tag }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      
+
       - name: Create tag
         working-directory: ${{ github.workspace }}/scripts/ci
         run: node create-tag.js
diff --git a/docs/plugin-maintainers-guide.md b/docs/plugin-maintainers-guide.md
new file mode 100644
index 0000000000..f94abcc4cf
--- /dev/null
+++ b/docs/plugin-maintainers-guide.md
@@ -0,0 +1,36 @@
+# Plugin Maintainer Guide
+
+## Table of Contents
+
+- [Plugin Maintainer Guide](#plugin-maintainer-guide)
+  - [Table of Contents](#table-of-contents)
+  - [Maintaining and patching an older release line](#maintaining-and-patching-an-older-release-line)
+    - [Patching an older release](#patching-an-older-release)
+
+## Maintaining and patching an older release line
+
+It may be necessary to patch a prior release line of a plugin when users depend on an older, but stable version and while a newer, incompatible, major version of the plugin exists. Typically for these older releases, only major bugs and security issues will need to be remediated. Not every plugin will need this workflow.
+
+This guide will describe the steps needed to release on an older version.
+
+### Patching an older release
+
+When patching an older release, follow the steps below to ensure the correct workflow is applied:
+
+1. Request a `workspace/${workspace}` branch:
+    - Ensure a branch with the name `workspace/${workspace}` exists and has appropriate branch protections in place. This branch will be used to handle patch releases.
+    - The `${workspace}` should correspond to the specific plugin or component you are patching.
+
+2. Reset the `workspace` branch:
+    - Reset the `workspace/${workspace}` branch to the version of the plugin you need to patch.
+    - You can use the autogenerated tags from previous releases to pinpoint the specific point in history to apply the patch.
+
+3. Apply your commits:
+    - Apply the necessary patch fixes or security updates.
+    - Manually bump the `package.json` version to reflect the new patch version (e.g., from `1.2.3` to `1.2.4`).
+
+4. Run the release workflow:
+    - Navigate to the GitHub Actions tab in your repository and manually trigger the release workflow.
+    - When prompted, specify your `workspace` (which will automatically infer the `workspace/${workspace}` branch based on the naming convention).
+    - Select the option `force release with no changesets`.
+    - The workflow will now run, building and releasing the patched version.