open-swe/docs/upstream-sync/cherry-pick-runbook.md

Cherry-picking upstream into the fork

This repository is a long-lived fork of langchain-ai/open-swe (git remote upstream). Upstream changes are brought in one commit at a time with git cherry-pick, and every diverged commit is tracked in a triage ledger so a decision is made once and not revisited. dev is the integration branch; the broader strategy lives in the fork-maintenance section of CLAUDE.md.

Setup (once per clone)

make install-hooks

Installs the triage hooks and the git cp alias by pointing core.hooksPath at .githooks/. Because that shadows the machine-global hook directory (~/.config/git/hooks, which holds the mandatory security pre-push), .githooks/pre-push is a shim that re-execs the global hook, and the installer verifies that delegation before it changes anything. git never auto-adopts a repository's core.hooksPath, so this step cannot be skipped.

Note: core.hooksPath applies repo-wide, but .githooks/ is a tracked directory. The hooks (and the security shim) only run on branches that actually contain .githooks/. Keep it present on dev and main so no branch loses the security pre-push.

Finding what to pick

make triage-sync    # git fetch upstream, then append new dev..upstream/main commits
                    # to the ledger as `untriaged` (PR # + subject parsed from each)

triage-sync is the discovery step: it records every diverged commit as untriaged and bumps "Last synced" to the new upstream/main tip. Triage those rows (decide deferred / wont-merge and which branch), then pick the ones you want. The underlying views if you prefer raw git:

git fetch upstream
git log --oneline --no-merges dev..upstream/main   # everything diverged
git show <sha>                                      # inspect before deciding

Cross-check candidates against the ledger first — most diverged commits already carry a decision (already-in-dev, regression, deferred, or landed) and should not be re-examined.

Bringing in commits: git cp

git cp -x <sha>              # pre-check the ledger, cherry-pick -x, auto-reconcile
git cp -x <sha1> <sha2> ...  # several, applied in the given order
git cp --continue            # after resolving a conflict; also reconciles
git cp --force <sha>         # override a SHA the ledger marks "Won't merge"

git cp reads docs/upstream-sync/triage.jsonl before touching the tree and refuses a known-reject SHA (override with --force). On success it runs make triage-reconcile, which moves each applied SHA to Landed in the ledger and stages triage.jsonl + triage.md for you to commit.

Apply commits in upstream chronological order (oldest first), not the order you happen to list them — a later commit often depends on an earlier one, and out-of-order picks conflict needlessly:

git log --reverse --topo-order --format=%h dev..upstream/main

The triage ledger

docs/upstream-sync/triage.jsonl is the source of truth: one JSON row per upstream SHA, keyed on the SHA (stable, unlike the local SHAs cherry-pick rewrites). docs/upstream-sync/triage.md is generated from it and must not be hand-edited. Dispositions are landed, wont-merge, deferred, untriaged.

scripts/triage.py set <sha> --disposition deferred --branch slack-tooling --reason "..."
make triage-render      # regenerate triage.md from the jsonl
make triage-check       # CI gate: fail if triage.md is stale

A SHA marked wont-merge is hard-blocked by both git cp and the prepare-commit-msg hook. Override for a one-off re-evaluation with git cp --force, SH_CHERRYPICK_ALLOW_REJECT=1, or git config sh.cherrypick.blockRejects false.

Branch layout

Never cherry-pick onto dev directly. Work on a themed branch off dev and open a PR into dev; the ledger's branch column records where each deferred commit is meant to land (for example slack-tooling, gateway-routing, plan-approval, durable-dispatch). Keep each PR to one theme so conflict resolution stays within one subsystem.

Raw git cherry-pick

The hooks fire on a plain git cherry-pick -x <sha> too: post-commit journals each applied pick and prepare-commit-msg blocks known-rejects. Run make triage-reconcile once at the end to land the picks in the ledger, then commit triage.jsonl + triage.md.

Conflicts

# resolve the files, then:
git add <files>
git cherry-pick --continue    # or: git cp --continue
git cherry-pick --abort       # bail out of the whole pick
git cherry-pick --skip        # drop just this commit and continue the batch

A commit that conflicts because dev already carries a newer version of the same code is a regression, not a merge — skip it and record the decision as wont-merge in the ledger rather than forcing it in.