backport

# Backporting a Pull Request Automates the patch-release backport flow from [`RELEASING.md`](../../../RELEASING.md) §Patch Releases. Invoke as: ``` /backport <PR-number> [target-branch] ``` Requires an authenticated [`gh`](https://cli.github.com/) 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: ```sh 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: ```sh 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 ```sh 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: ```sh git rev-parse --verify --quiet "${MERGE}^2" ``` - **Merge commit** (`^2` resolves): the PR's commits are preserved in `main`. ```sh 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: ```sh 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. #### Inspecting a conflict before resolving Conflict markers can include unrelated `main`-only lines that anchored the hunk's context. Naively accepting "incoming" smuggles those into the backport. Before resolving, run `git show <sha> -- <conflicted-file>` to show the authoritative diff. If the `>>>>>>>` side has extra lines `git show` doesn't list, drop them. #### Locale files `src/i18n/locales/*.json` conflict constantly. Keys are sorted alphabetically and every locale carries every key. Resolve per key, not per hunk: - Take only the keys the picked commit actually adds or changes, leave the rest at the target branch's state. - A new key goes into `en.json` with its English value and into **every** other locale file with a `null` value. - Run `npm run prettier-fix` afterwards to restore key order and formatting. ### 5. Manual commit format For manually-recreated commits (not cherry-picked): - Mirror the original subject + body. - Add `Co-Authored-By: <Name> <email>` for the original commit's author. Omit if that email equals `git config user.email`. Never add `Co-Authored-By: Claude ...`. - `git commit -s` (adds `Signed-off-by`). Author identity = default git config. Pass the message via HEREDOC. ### 6. Post-backport checks Run from the worktree. Anything beyond the first row needs dependencies first: `npm ci` (uses the target branch's `package-lock.json`, never copy or symlink `node_modules` from the primary checkout, the lockfiles differ across branches). | If any commit touches | Run | | ------------------------------------------- | --------------------------------------- | | nothing but `.github/**`, `docker/**`, docs | nothing | | `src/i18n/locales/**` | `npm run vue-i18n-extract` | | `src/**`, `package.json`, `*.config.js` | `npm run prettier` then `npm run build` | `npm run eslint` is covered by [`lint.yaml`](../../../.github/workflows/lint.yaml) in CI and is slow locally. Run it only if a resolution changed non-trivial logic. On failure, report and stop. ### 7. Summary Print, in this order: 1. The worktree path. 2. One row per commit from step 2. Every commit gets a row, including skipped ones: | Status | Commit | Subject | | ------------------------------------------- | ------------- | ------- | | `picked` / `manual` / `skipped` / `already` | `<short-sha>` | ... | `<short-sha>` is the source commit on `main`, not the new one. For `skipped`, give the reason. 3. The push command (DO NOT RUN IT): ```sh cd .claude/worktrees/backport-pr-<N> && git push -u origin backport-pr-<N> ``` If any row is not `picked`, state that on one line above the table.