diff --git a/docs/initiatives/auto-rebase-vs-merge-queue.md b/docs/initiatives/auto-rebase-vs-merge-queue.md new file mode 100644 index 000000000..69d697032 --- /dev/null +++ b/docs/initiatives/auto-rebase-vs-merge-queue.md @@ -0,0 +1,149 @@ +# Initiative: Auto-rebase Fan-out Reduction — Decision Record & Merge Queue Go/No-Go Gate + +**Status:** Decision record — free mitigation validated (≥50% metric met); Merge Queue go/no-go **deferred to a human** (epic [#736](https://github.com/petry-projects/.github-private/issues/736) open question) +**Author:** dev-lead / Claude Code +**Date:** 2026-06-21 +**Scope (confirmed):** Records the measured before/after impact of the **review-ready auto-rebase +fan-out restriction** (the free, plan-independent mitigation from epic [#736](https://github.com/petry-projects/.github-private/issues/736), +Story [#738](https://github.com/petry-projects/.github-private/issues/738)) and the now-measurable +agentic-conflict-resolution rate (Story [#737](https://github.com/petry-projects/.github-private/issues/737)). +Defines the GitHub **Merge Queue** go/no-go as explicit, checkable gate conditions. Does **not** decide +the go/no-go — that remains a human call (see §4). +**Constraints (confirmed):** Docs-only. The before/after numbers are sourced from the Story 1 (#737) +observability report and the discussion [#735](https://github.com/petry-projects/.github-private/discussions/735) +manual baseline — not re-estimated here. Fan-out volume is an **estimate** (per-run behind-PR counts +live in the central reusable, not this repo); it is labelled as such throughout, consistent with the +Story 1 report's method note. + +--- + +## 1. What was changed, and why + +Branch protection's "Require branches to be up to date" serializes merges: every merge to `main` leaves +all other open PRs behind. The `Auto-rebase non-Dependabot PRs` workflow papered over that by calling +`update-branch` on **every** behind non-Dependabot PR on every push to `main` — fanning a fresh CI run +onto each. At the repo's measured throughput (~12.3 merges/day, ~14–18 concurrently-open PRs) that was +an estimated **~170–220 redundant branch-update CI runs/day** (discussion #735), the bulk of which were +re-staled by the next merge before any human looked at them. + +Epic #736 split the response into two tiers: + +1. **Free, plan-independent mitigation (Story #738):** stop fanning out to PRs nobody will review — + restrict the update to a **review-ready eligibility predicate**. Landed **2026-06-15** in the central + reusable via PR [petry-projects/.github#468](https://github.com/petry-projects/.github/pull/468) + (issue #465). Predicate: **non-draft AND (current `APPROVED` review OR `auto-rebase:ready` label)**, + tunable via an `eligibility` workflow input. The merge-method update (approval-safe) and the + `