OmniRoute/docs/ops/MERGE_TRAIN.md

title

title
Merge Queue & Manual Merge-Train Runbook

Merge Queue & Manual Merge-Train Runbook

Since v3.8.49 (WS3.2/WS3.4 of the quality/velocity plan) the default merge path for reviewed PRs into release/vX.Y.Z is the Mergify merge queue (.mergify.yml); the manual merge-train documented below is the FALLBACK — used during incidents, release freezes, or if the Mergify Open Source plan ever changes.

Default path: the Mergify queue

1. PR is reviewed/greened by the campaigns and approved by the owner's pre-merge ⭐ gate (the report + per-item decision — see /merge-prs Step 0.75).
2. The owner (or the session acting on the owner's decision) applies the queue label. The label IS the merge approval; Mergify only executes it.
3. Mergify batches up to 10 queued PRs, validates the batch against the fast-gates, and merges (squash). A red batch is bisected automatically — the offending PR is isolated in ~log2(N) revalidations and unqueued; the rest proceed.
4. Post-merge, the continuous release-green workflow validates the new tip on push and opens an attribution issue if the combination regressed (never auto-revert).

Guardrails (mirror CLAUDE.md Hard Rules #21/#22):

• Release freeze open → do NOT label PRs targeting the frozen branch; retarget to the active release/vX+1 first.
• Another session's in-flight PR → never label it; only the owning session queues its own work.
• Tests-only diffs and hotfix-labeled PRs already run reduced CI (see RELEASE_CHECKLIST.md → Hotfix Fast-Lane); the queue conditions accept whatever check set actually ran (#check-failure=0 + #check-pending=0).

Fallback: the manual merge-train

Used when the queue is unavailable. This codifies the practice that drained 33 PRs in one day during the v3.8.47 cycle:

1. Assemble the batch (~10–30 reviewed+approved PRs). Check linked: collisions (same tap.testFiles, same CHANGELOG hunks) and serialize those.
2. Validate ONCE: in an isolated worktree off the release tip, merge all batch heads locally, then run the release-equivalent suite (npm run check:release-green, add --with-build before a release). scripts/release/merge-train.sh <base> <PR#>… automates steps 1–2 (conflicting PRs eject, the train continues). Full mode runs npm run test:unit — the box-tuned runner (--test-concurrency=20), not the two sequential 4-core CI shards, which drove the dominant phase at ~25% of a 16-core box (fixed 2026-07-18). --fast (intra-day mega-train drains, owner-approved 2026-07-18) keeps every static gate + vitest but runs only the node:test files changed by the boarded PRs; the FULL suite must still run at least once per day on the accumulated tip (one train without --fast).
3. Green → merge the PRs in sequence (re-checking state,headRefOid before each — a PR whose head moved re-enters review). Prove the net diff of each merge is the PR's own change (no auto-resolve reverts: audit git diff --stat for out-of-scope deletions).
4. Red → bisect the batch by halves (validate each half) instead of re-validating one-by-one; drop the offending PR back to the review queue with the evidence.
5. Never: merge during a freeze into the frozen branch; git stash anywhere; blanket-rerun CI hoping a red goes away (rule: a red is information).

Tiering (why the queue is safe with fast-gates only)

• Per PR (quality.yml fast-gates): TIA-impacted tests + full unit 4-shard + vitest + lint bag + typecheck + docs/changelog integrity.
• Per batch/tip (continuous release-green): --quick HARD gates on every push to the release branch; full --with-build --full-ci sweeps 3×/day.
• Per release (ci.yml on the release PR): the complete matrix incl. E2E ×9, package-artifact + tarball boot-smoke, coverage/ratchets.

Nothing is validated less than before — the heavy surface just runs per batch/tip instead of per PR, which is what removes the O(N) round-trips.