[docs] How to cherry-pick to pre-monorepo branches

docs/how-to-cherry-pick-monorepo-changes-to-release-staging.md

@@ -0,0 +1,67 @@
+# How to cherry-pick monorepo changes into release-staging branches
+
+> [!IMPORTANT]
+> This document is currently in **draft** and may be subject to change.
+
+When a project has been migrated into the ROCm monorepo, day-to-day work happens on the monorepo’s `develop` branch.  
+Down-stream teams, however, still consume the original (pre-monorepo) repositories, particularly their `release-staging/rocm-rel-x.y` branches, through a variety of mechanisms.
+This document explains how to move a change from the monorepo into those release-staging branches while guaranteeing that every commit on a release-staging branch also exists in the monorepo.  
+
+## 1. Land the change in the monorepo's develop branch
+
+1. Create a pull request in `ROCm/rocm-libraries` that targets `develop`.  
+2. When merging, choose **Squash & Merge** (if the change can be represented as a single logical commit).  
+   Why? A single commit is easier to cherry-pick later.
+
+Result: The commit is now on `ROCm/rocm-libraries:develop`.
+
+## 2. Cherry-pick into the monorepo's release-staging branch
+
+1. Create a local branch based on the release-staging branch:
+
+```
+$ git checkout -b cherry-pick-foo-rel-x.y origin/release-staging/rocm-rel-x.y
+```
+
+2. Cherry-pick the commit:
+
+```
+$ git cherry-pick abcd1234 
+```
+
+3. Resolve any merge conflicts (rare if the branch is close to develop).
+4. Push the branch and open a PR that targets `ROCm/rocm-libraries:release-staging/rocm-rel-x.y`.
+5. Request reviews, obtain approvals, and merge.
+
+## 3. Wait for the automatic “fan-out” sync
+
+Every ~15 minutes, a CI job copies new commits from the monorepo back into the corresponding standalone repositories.
+
+After merging your PR:
+
+1. Monitor the CI job or simply wait ~15 minutes.  
+2. Go to the original (pre-monorepo) repository and verify the commits have been reflected onto the `develop` and `release-staging/rocm-rel-x.y` branches.
+
+## FAQ
+
+Q : Can I cherry-pick multiple commits at once?  
+A : Yes, but prefer a squash merge in the monorepo so you only need to pick one.
+
+Q : What if the auto-sync hasn’t copied the commit?  
+A : Verify the CI status in `rocm-libraries`. If failed, ask the infra team; the commit will re-sync after a successful run.
+
+Q : Can I push directly to the release-staging branch?  
+A : No. Always go through a PR so CI and reviewers can validate the cherry-pick.
+
+Q : What if commits have been pushed to develop that make a cherry-pick incompatible with release-staging?   
+A : It's likely that this fix/change will also be landed in develop at some point, else we risk divergent features/support. So, it's recommended to still land the change in develop first, and cherry-pick to release-staging, resolving any merge conflicts that arise. If for some reason the develop branch has diverged so far from the release-staging for your component that a cherry-pick is irreconcilable, land the changes in develop and release-staging using fully separate PRs, and add references to the other for traceability.
+
+## Summary
+
+In short:
+
+1. Merge change to monorepo `develop`.  
+2. Cherry-pick to monorepo `release-staging/rocm-rel-x.y`.  
+3. Wait for the fan-out sync and verify the changes are reflected in the original repository.
+
+Following this process keeps release branches in sync with the monorepo while allowing critical fixes to flow to down-stream consumers.