chore(docs): migrate relevant docs from BCP, including backport guide (#2741)

* chore(docs): migrate relevant docs from BCP, including backport guide

Signed-off-by: Hope Hadfield <hhadfiel@redhat.com>

Author: hopehadfield

CONTRIBUTING.md

@@ -14,6 +14,8 @@ The `redhat-developer/rhdh-plugins` repository is designed as a collaborative sp
   - [Versioning](#versioning)
   - [Creating Changesets](#creating-changesets)
   - [Release](#release)
+  - [Backporting patches (prior release lines)](#backporting-patches-prior-release-lines)
+    - [Patching an older release](#patching-an-older-release)
   - [Creating a new Workspace](#creating-a-new-workspace)
   - [Creating new plugins or packages in a Workspace](#creating-new-plugins-or-packages-in-a-workspace)
   - [Migrating a plugin](#migrating-a-plugin)
@@ -73,6 +75,8 @@ There could be times when there is a need for a more rich development environmen
 
 ## Coding Guidelines
 
+For consistency across the monorepo, we suggest following the same Yarn setup as the repository root: the Yarn release is defined in the root `package.json` and `.yarnrc.yml`, and individual workspaces generally should not pin a different Yarn version.
+
 All code is formatted with `prettier` using the configuration in the repo. If possible we recommend configuring your editor to format automatically, but you can also use the `yarn prettier --write <file>` command to format files.
 
 ## Versioning
@@ -115,6 +119,58 @@ A release is automatically triggered by merging the plugins “Version Packages
 > [!Important]
 > Please note that plugins with the private property set to 'true' will not be published upon merging the "Version Packages" PR. If you want full autonomy over the release process, you can mark your plugin as private. In this case, the release process will be managed by the plugin maintainer.
 
+## 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.
+
+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
+
+When patching an older release, follow the steps below to ensure the correct workflow is applied:
+
+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.
+
+   The workflow requires that pull requests targeting the `workspace/${workspace}` branch be opened from a branch within the `redhat-developer/rhdh-plugins` repository. Therefore, in addition to the `workspace/${workspace}` branch, a corresponding branch must also be created (i.e. `plugin-name-x.y`).
+
+   If a branch `maintenance-changesets-release/${workspace}` 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. Reset the `workspace` branch from a **published** baseline:
+   - Reset `workspace/${workspace}` so it matches an existing **git tag** for that workspace (the tags created when releases were published), not an arbitrary commit on `main`. That way the maintenance line starts from code that was already shipped and you avoid accidentally including unreleased changes in the next npm publish.
+   - Browse tags in the repository to find the right release: [github.com/redhat-developer/rhdh-plugins/tags](https://github.com/redhat-developer/rhdh-plugins/tags).
+
+3. Apply your commits 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.
+   - Push to a branch on the `redhat-developer/rhdh-plugins` repository. Note that it is not possible to open PRs from a fork for this release workflow.
+
+4. Open the **patch** pull request (the first PR in this flow):
+   - Open a pull request with your changes against the `workspace/${workspace}` branch.
+   - Ensure the PR:
+     - Contains only necessary fixes.
+     - Includes a changeset.
+
+5. Merge the **patch** PR when it is 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/${workspace}`, authored by `rhdh-bot`.
+
+6. 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/${workspace}` 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.
+
+7. 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.
+
+8. 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.
+   - You can use `git cherry-pick --no-commit workspace/${workspace}` and only commit the `CHANGELOG` files.
+
 ## Creating a new Workspace
 
 For workspaces the name should reflect the name of the plugins contained in a simple manner (e.g. for the plugins `todo` & `todo-backend` the workspace would be called `todo`).
@@ -253,6 +309,8 @@ Once PRs are merged in the new repo, you should [mark the old plugins deprecated
 
 As only a single version will be migrated to the new repo, maintenance of older plugins for previous RHDH releases should continue to be done in the older repo, as the migrated versions will be aligned to newer versions of Backstage and may not be compatible.
 
+For packages **already released from this repository** at an older version, use [Backporting patches (prior release lines)](#backporting-patches-prior-release-lines) instead.
+
 ## API Reports
 
 This repository uses [API Extractor](https://api-extractor.com/) and TSDoc comments to generate API Reports in Markdown format, similar to those used in Backstage. If you make changes to the API or add a new plugin then you will need either generate a new API Report or update an existing API Report. If you don't do this the CI build will fail when you create your Pull Request.
@@ -314,8 +372,7 @@ As a plugin owner, you are responsible for the ongoing health and maintenance of
   See [Keeping Workspaces Up to Date](#keeping-workspaces-up-to-date-with-backstage).
 - **Manage security updates and patches**:
   Work with your security team to address vulnerabilities according to SLA and product lifecycle requirements.
-  Since this repository does not maintain release branches, Renovate only opens PRs against the latest code.
-  If your plugin is used in multiple product versions, you are responsible for backporting critical patches.
+  Renovate opens dependency PRs against `main`. If you must ship a fix on an older published line, follow [Backporting patches (prior release lines)](#backporting-patches-prior-release-lines) using the `workspace/<workspace>` branch for that line.
 - **Justify Dependency-Related PR closures**:
   If you choose not to merge a Renovate or dependency-related PR, include a brief explanation when closing it.