| name | cherry-pick-main-to-release |
| description | Cherry-pick a merged pull request's commit(s) from `main` onto the current release branch and open a draft PR. |
| disable-model-invocation | true |
| allowed-tools | Read, Bash(which gh), Bash(git fetch *), Bash(git branch *), Bash(git branch -r *), Bash(git checkout *), Bash(git switch *), Bash(git cherry-pick *), Bash(git status *), Bash(git log *), Bash(git show *), Bash(git rev-list *), Bash(git push *), Bash(grep *), Bash(sed *), Bash(sort *), Bash(tail *), Bash(gh pr view *), Bash(gh pr create --repo Automattic/pocket-casts-android *), Bash(gh pr edit --repo Automattic/pocket-casts-android *), Bash(gh pr list --repo Automattic/pocket-casts-android *) |
Cherry-pick a PR to the release branch
Take a merged pull request, cherry-pick its commit(s) onto a fresh branch off the current release branch, and open a draft PR
targeting that release branch.
The workflow this supports: fixes are developed and merged on main, then cherry-picked to the release branch. That keeps the release branch
limited to exactly the commits it needs, so merging it back into main later is clean and unambiguous (see the Git Workflow section of AGENTS.md).
Requirements
- GitHub CLI (
gh) installed and authenticated. Verify with which gh; if missing, stop and tell the user to install it.
- The PR URL (or number) to cherry-pick. If the user did not provide one, ask for it.
Steps
1. Read the source PR
Run:
gh pr view <pr-url-or-number> --repo Automattic/pocket-casts-android \
--json number,title,url,state,mergedAt,mergeCommit,headRefName,author,labels,body
- If
state is not MERGED, warn the user: cherry-picking is meant for changes already reviewed and merged on main. Ask whether to continue
anyway before proceeding.
- Note the
mergeCommit.oid (the commit that landed on main). This is what you will cherry-pick.
2. Determine the current release branch
There should be only one active release branch. Fetch and find the highest version:
git fetch origin --prune
git branch -r | grep -oE 'origin/release/[0-9]+\.[0-9]+' | sed 's|origin/release/||' | sort -V | tail -1
This prints the latest release version (e.g. 8.15), giving the branch release/<ver>. There is normally only one active release branch, so use
the one you find without asking. Only pause to confirm with the user if the command returns more than one release branch, in which case ask
which to target.
3. Identify the commit(s) to cherry-pick
The repository squash-merges PRs, so the merge commit is usually a single commit containing the whole change. Handle both squash and true merge
commits by checking the parent count:
git rev-list --parents -n 1 <mergeCommit.oid>
If mergeCommit is null (rare, e.g. the PR was merged in an unusual way), or the PR was rebase-merged (each commit is replayed onto main, so
mergeCommit.oid is only the last of them and cherry-picking it alone would silently drop the earlier commits), fall back to the PR's own commits
from gh pr view --json commits and cherry-pick them in order, oldest first. Tell the user this is what you are doing.
4. Create the branch off the release branch
Branch from the release branch, never from main. Use a descriptive name that ties it to the source PR:
git checkout -b cherry-pick/<ver>/pr-<number> origin/release/<ver>
5. Cherry-pick
Run the cherry-pick command chosen in step 3.
- On success, verify with
git log --oneline -n 3 that the commit landed.
- On conflict, stop. Show the conflicting files (
git status) and hand back to the user to resolve. Do not force or guess a resolution. Once
they have staged the fixes, continue with git cherry-pick --continue. Resolving conflicts carefully matters here because the release branch and
main may have diverged.
6. Push and open the draft PR
git push -u origin cherry-pick/<ver>/pr-<number>
Create a draft PR targeting the release branch, filling in the template below:
gh pr create --repo Automattic/pocket-casts-android --draft \
--base release/<ver> \
--head cherry-pick/<ver>/pr-<number> \
--title "<original title> (cherry-pick to <ver>)" \
--body "<filled-in body>"
7. Carry over labels and report
PR body template
Fill in every field. The body must make clear this is an already-reviewed change being cherry-picked, while still asking reviewers/CI to confirm it
applies cleanly, because the release branch may have diverged from main.
## Description
Cherry-pick of #<original-number> into `release/<ver>`.
> **This change was already reviewed and merged on `main`.** This PR exists to land it in the upcoming release. CI and a quick review should still
> run to confirm the cherry-pick applies cleanly and introduces no issues on the release branch, since `release/<ver>` may have diverged from `main`.
- Original PR: <original-url>
- Cherry-picked commit: `<mergeCommit.oid short sha>`
## Testing Instructions
See the original PR (<original-url>) for full testing steps. In addition, verify the change behaves as described on top of `release/<ver>`.
