feat: support release-x.y/{plugin} branches for Version Packages workflow

.github/workflows/release_workspace_version.yml

@@ -1,27 +1,24 @@
 name: Prior Version Release Workspace
 
 on:
-  # ADDED: Only trigger on PR closed event on workspace/** branch.
-  #        The assumption is that branch protection rules and CODEOWNERS are configured.
-
   pull_request:
     types:
       - closed
     branches:
       - 'workspace/**'
+      - 'release-*/*'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
-    # ADDED: Checks if PR is a Version Packages PR on workspace/** branch
-    #        and validates PR title, author, branch and merged status.
   check-merged-pr:
-    name: Check if PR is a Version Packages PR on workspace/** branch
+    name: Check if PR is a Version Packages PR
     runs-on: ubuntu-latest
     outputs:
         is_version_pr: ${{ steps.check_pr.outputs.is_version_pr }}
         workspace_name: ${{ steps.extract_workspace.outputs.workspace_name }}
+        version_branch_id: ${{ steps.extract_workspace.outputs.version_branch_id }}
     steps:
         - name: Check PR title, author, branch and merged status
           id: check_pr
@@ -40,14 +37,23 @@ jobs:
                 echo "is_version_pr=false" >> $GITHUB_OUTPUT
               fi
 
-        # ADDED: Extracts workspace name from branch, ensuring it is a workspace/** branch
         - name: Extract Workspace name from branch
           id: extract_workspace
           env:
             BASE_REF: ${{ github.event.pull_request.base.ref }}
           run: |
-              WORKSPACE_NAME=$(echo "$BASE_REF" | cut -d'/' -f2)
+              if [[ "$BASE_REF" == workspace/* ]]; then
+                WORKSPACE_NAME=$(echo "$BASE_REF" | cut -d'/' -f2)
+                VERSION_BRANCH_ID="$WORKSPACE_NAME"
+              elif [[ "$BASE_REF" == release-*/* ]]; then
+                WORKSPACE_NAME=$(echo "$BASE_REF" | cut -d'/' -f2)
+                VERSION_BRANCH_ID="$BASE_REF"
+              else
+                WORKSPACE_NAME=$(echo "$BASE_REF" | cut -d'/' -f1)
+                VERSION_BRANCH_ID="$WORKSPACE_NAME"
+              fi
               echo "workspace_name=$WORKSPACE_NAME" >> $GITHUB_OUTPUT
+              echo "version_branch_id=$VERSION_BRANCH_ID" >> $GITHUB_OUTPUT
 
   changesets-pr:
     name: Update Version Packages PR for ${{ needs.check-merged-pr.outputs.workspace_name }} on branch ${{ github.ref }}
@@ -70,10 +76,10 @@ jobs:
 
       - name: Verify maintenance-changesets-release branch does not exist
         env:
-          WORKSPACE_NAME: ${{ needs.check-merged-pr.outputs.workspace_name }}         
+          VERSION_BRANCH_ID: ${{ needs.check-merged-pr.outputs.version_branch_id }}
         run: |
-          if git ls-remote --exit-code origin "refs/heads/maintenance-changesets-release/$WORKSPACE_NAME"; then
-            echo "Error: maintenance-changesets-release/$WORKSPACE_NAME branch already exists. Please clean up the branch before proceeding."
+          if git ls-remote --exit-code origin "refs/heads/maintenance-changesets-release/$VERSION_BRANCH_ID"; then
+            echo "Error: maintenance-changesets-release/$VERSION_BRANCH_ID branch already exists. Please clean up the branch before proceeding."
             exit 1
           fi
 
@@ -126,7 +132,7 @@ jobs:
           title: Version Packages (${{ needs.check-merged-pr.outputs.workspace_name }})
           cwd: workspaces/${{ needs.check-merged-pr.outputs.workspace_name }}
           version: yarn changeset version
-          versionBranch: maintenance-changesets-release/${{ needs.check-merged-pr.outputs.workspace_name }}
+          versionBranch: maintenance-changesets-release/${{ needs.check-merged-pr.outputs.version_branch_id }}
           skipRootChangelogUpdate: true
         env:
           GITHUB_TOKEN: ${{ secrets.RHDH_BOT_TOKEN }}

CONTRIBUTING.md

@@ -122,13 +122,54 @@ A release is automatically triggered by merging the plugins “Version Packages
 
 ## Backporting patches (prior release lines)
 
-Use this flow when you need a **new npm version** of packages in a workspace that tracks an older line than `main` (for example a security or bugfix for a release already shipped to customers). Day-to-day development and Renovate updates still happen on `main`; the `workspace/<name>` branch is only for those maintenance releases.
+Use this flow when you need a **new npm version** of packages in a workspace that tracks an older line than `main` (for example a security or bugfix for a release already shipped to customers). Day-to-day development and Renovate updates still happen on `main`; the backport branch is only for those maintenance releases.
 
 Automation for this path is defined in [`.github/workflows/release_workspace_version.yml`](.github/workflows/release_workspace_version.yml). Published packages from this workflow use the npm dist-tag **`maintenance`** so they do not replace `latest`.
 
-### Patching an older release
+There are two branch strategies available. The **recommended** approach uses `release-x.y/{plugin}` branches, which support concurrent backports to different release versions without conflicts.
 
-When patching an older release, follow the steps below to ensure the correct workflow is applied:
+### Recommended: `release-x.y/{plugin}` branches
+
+This approach uses per-release branches (e.g., `release-1.10/my-plugin`), eliminating the shared `workspace/{plugin}` branch as an intermediary. Multiple backports to different releases can proceed concurrently without blocking each other.
+
+1. Verify a `release-x.y/${plugin}` branch exists (e.g., `release-1.10/my-plugin`). If not, create it from the appropriate release tag by navigating to the [branches page](https://github.com/redhat-developer/rhdh-plugins/branches) and selecting 'New branch'.
+
+   If a branch `maintenance-changesets-release/release-x.y/${plugin}` already exists on the remote from a previous cycle, delete it before continuing; otherwise the Prior Version Release Workspace workflow will refuse to open a new Version Packages PR.
+
+2. Cherry-pick the target commit(s) from `main` and push to a branch:
+   - Apply the necessary patch fixes or security updates.
+   - Do not manually bump the version in `package.json`. The version bump must be handled via changesets.
+   - A changeset **must** be included in the PR to trigger a new release.
+
+   ```bash
+   git fetch upstream
+   git checkout -b backport-<pr>-to-<release> upstream/release-x.y/<plugin>
+   git cherry-pick <commit-sha>
+   git push origin backport-<pr>-to-<release>
+   ```
+
+3. Open a pull request targeting the `release-x.y/${plugin}` branch and merge when approved and CI is green.
+
+   Merging this PR does **not** publish to npm by itself. It triggers the Prior Version Release Workspace workflow, which opens a **separate** follow-up pull request—the **Version Packages** PR—from branch `maintenance-changesets-release/release-x.y/${plugin}`, authored by `rhdh-bot`.
+
+4. Merge the corresponding **Version Packages** PR:
+   - The Version Packages PR must meet these conditions before you merge it:
+     - The PR title starts with "Version Packages" (automatically generated by changesets).
+     - The PR originates from a `maintenance-changesets-release/release-x.y/${plugin}` branch.
+     - The PR is authored by `rhdh-bot`.
+     - The PR is merged, not just closed.
+   - Merging **this** PR triggers the release job that builds and publishes to npm.
+
+5. Confirm the release:
+   - Once the workflow completes, a new version will be published.
+   - A new Git tag will be created, which can be used for future patches.
+
+6. Open a PR with the `CHANGELOG` additions to `redhat-developer/rhdh-plugins` main branch:
+   - This is necessary for history to be clear on the latest branch.
+
+### Legacy: `workspace/{plugin}` branches
+
+> **Note:** This approach uses a shared `workspace/{plugin}` branch, which blocks concurrent backports to different releases for the same plugin. Use the `release-x.y/{plugin}` approach above when possible.
 
 1. Verify a `workspace/${workspace}` branch exists. If not, create a `workspace/${workspace}` branch by navigating to the [branches page](https://github.com/redhat-developer/rhdh-plugins/branches) and selecting 'New branch'.
    - The `${workspace}` should correspond to the specific plugin or component you are patching.