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

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.