ci(release_workspace): add additional checks and document workflow

.github/workflows/release_workspace.yml

@@ -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

docs/plugin-maintainers-guide.md

@@ -0,0 +1,38 @@
+# 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 that a branch named `workspace/${workspace}` exists, with appropriate branch protections in place. This branch will be used for 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 version tags from previous releases to pinpoint the prior release version to apply the patch.
+
+3. Apply your commits:
+    - Apply the necessary patch fixes or security updates.
+    - Manually bump the version in `package.json` 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 the `workspace` (this refers to the workspace which contains the plugin you are patching).
+      - Specify the `branch` you are patching. It must correspond to the workspace specified following the `workspace/${workspace}` convention.
+      - Select the `force release with no changesets` option.
+    - The workflow will run, building and releasing the patched version. A new version tag will be published which you can use as the base for future patch/maintenance releases.