Backport

Backporting a Pull Request

Automates the patch-release backport flow from RELEASING.md §Patch Releases. Invoke as:

/backport <PR-number> [target-branch]

Requires an authenticated gh CLI (gh auth status).

Rules (DO NOT VIOLATE)

• Never git push. Print the push command at the end and let the user run it.
• Never add Co-Authored-By: Claude ... to any commit.
• Always cherry-pick with git cherry-pick -x -s (records origin SHA, adds signoff, matches existing patch-branch history).
• Always work in .claude/worktrees/backport-pr-<N>, never in the primary checkout.
• Never hand-format code. If a resolution touches source, run npm run prettier-fix before committing.
• If a conflict cannot be resolved unambiguously and does not apply conceptually, ask the user via AskUserQuestion. DO NOT IMPROVISE.

Resolving the canonical remote

origin may point at a fork. Resolve the canonical remote once and use $CANON everywhere below:

CANON=$(git remote -v | awk '/DependencyTrack\/frontend.*\(fetch\)/ {print $1; exit}')

If empty, ask the user which remote tracks the canonical repo.

Workflow

1. Validate state

• Confirm CWD is the primary repo (not already a worktree).

• Resolve $CANON per §Resolving the canonical remote, then git fetch $CANON.

• If target-branch was omitted, derive it from the PR's backport label:

  gh pr view <N> --json labels -q '.labels[].name | select(startswith("backport/"))'

  If backport/5.0.5, the target branch is 5.0.x. On zero or multiple matches, ask the user via AskUserQuestion, offering branches matching [0-9]+\.[0-9]+\.x.

2. Locate the PR's commits

gh pr view <N> --json state,baseRefName,mergeCommit

• state is not MERGED: abort. DO NOT GUESS.
• baseRefName is not main: tell the user which branch the PR targeted and ask before continuing. (master still exists on the remote but is stale. Treat it like any other unexpected base.)

Take MERGE from mergeCommit.oid, then check how it was merged:

git rev-parse --verify --quiet "${MERGE}^2"

• Merge commit (^2 resolves): the PR's commits are preserved in main.

  git log --reverse --format=%H "${MERGE}^1..${MERGE}^2"  # oldest first

• Squash or rebase merge (^2 missing): MERGE itself is the only commit to pick.

3. Set up the worktree

Path: .claude/worktrees/backport-pr-<N> (in-tree, git-ignored).

• Reuse (path exists, worktree registered): cd in, verify git status is clean (else ask the user), then git checkout -B backport-pr-<N> $CANON/<target-branch>.
• Fresh: git worktree add -b backport-pr-<N> .claude/worktrees/backport-pr-<N> $CANON/<target-branch>.
• Leftover branch (worktree gone, branch remains, git worktree add errors with a branch named '…' already exists): glance at git log backport-pr-<N> ^$CANON/<target-branch> to confirm nothing valuable, git branch -D backport-pr-<N>, retry.
• If git worktree add half-succeeded (partial directory plus a stale branch), delete both and git worktree prune before retrying.

A fresh worktree has no node_modules. Only install (§6) if a check actually needs it.

4. Apply each commit

For each SHA from step 2, in order.

First, skip what is already there:

git log $CANON/<target-branch> --grep="cherry picked from commit <sha>" --format=%H

Non-empty means already backported. Skip it and note that in the summary.

Otherwise git cherry-pick -x -s <sha>.

• Clean: continue.
• Trivial conflict (import order, non-overlapping adjacent edits): resolve, git add, GIT_EDITOR=true git cherry-pick --continue (--continue opens $EDITOR and hangs otherwise).
• Non-trivial but conceptually applies: git cherry-pick --abort, recreate manually, commit per §Manual commit format.
• Does not apply conceptually (target refactored/removed): git cherry-pick --abort, then AskUserQuestion with options (skip / reduced port / port differently). DO NOT INVENT A RESOLUTION.