From 3ea5c7559933d859c5b48f27ffaa25090c927374 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 21 May 2026 15:55:46 -0700 Subject: [PATCH 1/5] docs(merge-queue): rewrite overview for skeptical CI engineers Replaces marketing-style "Big Three problems" framing with a mechanics-first overview. Addresses Eli's feedback (2026-05-21): - "Big three items don't make sense or are outright lies" - "Calls out Nx/Bazel but not other build systems" - "Not selling - no clear audience, layout sucks" Page now: - Opens with a 2-paragraph hook that introduces predictive testing as the baseline every queue does, then names the three Trunk- specific layers (batching, parallel queues, anti-flake protection). - Gives each layer its own section with a plain-language mechanic explanation, the existing sub-page iframe, a one-line "what it costs you not to have it", and a link to the deep page. - Replaces "Native Bazel/Nx" with framing that includes any build system via the impacted-targets API. - Adds a "When does this make sense?" decision tree mapping symptom to mechanic in recognition voice. - Drops unsupported claims: "Batch up to 100 PRs", "cut CI costs up to 90%", "Automatic quarantine of flaky tests" (which was the wrong product entirely). - Strips marketing words per global style guide. Pattern captured for reuse on other product overviews at .claude/patterns/product-overview-for-skeptical-engineers.md (in main worktree, untracked). Co-Authored-By: Claude Opus 4.7 (1M context) --- merge-queue/merge-queue.mdx | 80 ++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 42 deletions(-) diff --git a/merge-queue/merge-queue.mdx b/merge-queue/merge-queue.mdx index 9039963..8b4ee25 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -1,73 +1,69 @@ --- title: "Overview" -description: "Merge queue that guarantees branch stability and accelerates development at enterprise scale" +description: "Trunk Merge Queue batches PRs, bisects failures, and routes non-overlapping changes into independent test lanes." --- -If you've hit the limits of GitHub's serial merge queue - main turning red, CI costs spiraling, chaos at scale - Trunk Merge Queue is the enterprise upgrade built for reliability at any scale. Handle your noisiest pipelines, cut CI costs up to 90%, and fire and forget. -*** +A merge queue sits between your developers and your protected branch. Instead of letting PRs merge as soon as their own CI passes, the queue tests each PR against the head of `main` plus every PR ahead of it — so what merges is what was actually tested, even when ten PRs land in the same hour. That predictive testing model is shared across most modern merge queues. -## Benefits of using Trunk Merge Queue +Trunk Merge Queue layers three things on top of that baseline: **batching** (test groups of PRs in one CI run), **parallel queues** (route non-overlapping changes into independent test lanes), and **anti-flake protection** (let a passing successor retroactively validate a failed predecessor). The rest of this page is how each one works and when it matters. -Trunk Merge Queue solves three critical problems that break traditional workflows at scale. +## Batching -### #1: Stop main from turning red +Instead of one CI run per PR, the queue groups several PRs together and tests them as a single unit. If the batch fails, automatic bisection isolates the culprit so passing PRs in the batch still merge — no manual debugging, no ejecting the whole batch. -**The problem:** Flaky tests fail unpredictably. Your team mutes tests, locks branches, and gets paged to investigate. + + + -**How Trunk fixes it:** Failed PRs stay in queue while downstream PRs continue testing. If a later PR that includes the failed code passes, Trunk knows the failure was transient, both PRs merge together. +**What it costs you not to have it:** every PR pays the full CI bill, even when ten land in the same hour. -**Key capabilities:** +→ See how [batching](./optimizations/batching) works. -* Anti-flake protection with optimistic merging -* Pending failure depth holds failed PRs while successors test, enabling automatic flake recovery -* Automatic quarantine of flaky tests +## Parallel queues -→ Learn about [anti-flake protection](./optimizations/anti-flake-protection) +Each PR reports which targets it touches. Non-overlapping PRs run in their own test lanes; only overlapping PRs share a lane. Bazel and Nx are first-class integrations; any other build system can report targets via the [impacted-targets API](./optimizations/parallel-queues/api). -*** + + + -### #2: Stop CI costs from spiraling +**What it costs you not to have it:** a two-line frontend fix waits 45 minutes behind a slow backend PR because they share a single queue. -**The problem:** GitHub runs full CI for every PR. 50 PRs/day = 50 full runs. With growing teams, CI costs become seven figures. +→ Explore [parallel queues](./optimizations/parallel-queues/). -**How Trunk fixes it:** Intelligent batching tests up to 100 PRs in a single CI run. When a batch fails, automatic bisection isolates the culprit without ejecting the entire batch or requiring manual debugging. +## Anti-flake protection -**Key capabilities:** +When a PR fails testing, the queue holds it in place while downstream PRs continue testing. If a downstream PR — which includes the failed PR's changes — passes, the failure was transient and both PRs merge. Two mechanics combine to make this work: [pending failure depth](./optimizations/pending-failure-depth) holds the failed PR, and [optimistic merging](./optimizations/optimistic-merging) lets a passing successor validate it retroactively. -* Intelligent Batching -* Batch up to 100 PRs -* Auto-Bisection -* Configurable batch size & wait time + + + -→ See how [batching](./optimizations/batching) works +**What it costs you not to have it:** flaky tests evict legitimate PRs from the queue and force manual retries. -*** +→ Learn about [anti-flake protection](./optimizations/anti-flake-protection). -### #3: Stop waiting in a serial queue +## When does this make sense? -**The problem:** Single-track queue means your 2-line fix waits 45 minutes behind a slow feature PR testing an unrelated part of the codebase. +- 50+ PRs/day, CI bill climbing → batching +- Monorepo with lanes of work that don't overlap → parallel queues +- Flaky tests blocking real merges → anti-flake protection +- Single-track GitHub Merge Queue choking → all three -**How Trunk fixes it:** Parallel queues create independent test lanes for non-overlapping changes. Frontend merges in Lane A while backend runs in Lane B. Native Bazel/Nx integration analyzes impacted targets automatically. +## More to dial in -**Key capabilities:** +Other optimizations worth knowing about: -* Parallel Queues -* Bazel/Nx integration -* Impacted targets analysis -* Priority merging +- [**Priority merging**](./optimizations/priority-merging) — fast-track urgent PRs (hotfixes, incident response) to the front of the queue without bypassing it +- [**Predictive testing internals**](./optimizations/predictive-testing) — how the foundational mechanic actually works +- [**Testing concurrency**](./administration/advanced-settings#testing-concurrency) — how many PRs the queue tests at once -→ Explore [parallel queues](./optimizations/parallel-queues/) +→ Full list in [Optimizations](./optimizations/). -*** +## Set it up -## Try Trunk Merge Queue - -**Start with free trial:** - -1. Install Trunk GitHub App (5 minutes) +1. Install the Trunk GitHub App (5 minutes) 2. Create your first queue (2 minutes) 3. Submit a test PR -**Total setup time: < 10 minutes** - -→ [Get started](./getting-started/) +→ [Get started](./getting-started/). From 111c4dba889652ba0ed057b351d144f381c66f8b Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 21 May 2026 16:09:34 -0700 Subject: [PATCH 2/5] docs(merge-queue): switch overview to Tiles layout Replaces the three stacked mechanic sections with a 3-column Tiles layout (boxes-stacked / columns-3 / shield-check icons + title + short description) that links each tile to its deep page. - Tighter at-a-glance preview of batching / parallel queues / anti-flake protection - Adds Direct merge to main to "More to dial in" (the one architectural optimization in the settings UI that wasn't already represented at the top) The Vidyard / iframely embeds drop off this page; they still live on the deep optimization pages. Co-Authored-By: Claude Opus 4.7 (1M context) --- merge-queue/merge-queue.mdx | 65 ++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 37 deletions(-) diff --git a/merge-queue/merge-queue.mdx b/merge-queue/merge-queue.mdx index 8b4ee25..4c902a1 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -5,43 +5,33 @@ description: "Trunk Merge Queue batches PRs, bisects failures, and routes non-ov A merge queue sits between your developers and your protected branch. Instead of letting PRs merge as soon as their own CI passes, the queue tests each PR against the head of `main` plus every PR ahead of it — so what merges is what was actually tested, even when ten PRs land in the same hour. That predictive testing model is shared across most modern merge queues. -Trunk Merge Queue layers three things on top of that baseline: **batching** (test groups of PRs in one CI run), **parallel queues** (route non-overlapping changes into independent test lanes), and **anti-flake protection** (let a passing successor retroactively validate a failed predecessor). The rest of this page is how each one works and when it matters. - -## Batching - -Instead of one CI run per PR, the queue groups several PRs together and tests them as a single unit. If the batch fails, automatic bisection isolates the culprit so passing PRs in the batch still merge — no manual debugging, no ejecting the whole batch. - - - - - -**What it costs you not to have it:** every PR pays the full CI bill, even when ten land in the same hour. - -→ See how [batching](./optimizations/batching) works. - -## Parallel queues - -Each PR reports which targets it touches. Non-overlapping PRs run in their own test lanes; only overlapping PRs share a lane. Bazel and Nx are first-class integrations; any other build system can report targets via the [impacted-targets API](./optimizations/parallel-queues/api). - - - - - -**What it costs you not to have it:** a two-line frontend fix waits 45 minutes behind a slow backend PR because they share a single queue. - -→ Explore [parallel queues](./optimizations/parallel-queues/). - -## Anti-flake protection - -When a PR fails testing, the queue holds it in place while downstream PRs continue testing. If a downstream PR — which includes the failed PR's changes — passes, the failure was transient and both PRs merge. Two mechanics combine to make this work: [pending failure depth](./optimizations/pending-failure-depth) holds the failed PR, and [optimistic merging](./optimizations/optimistic-merging) lets a passing successor validate it retroactively. - - - - - -**What it costs you not to have it:** flaky tests evict legitimate PRs from the queue and force manual retries. - -→ Learn about [anti-flake protection](./optimizations/anti-flake-protection). +Trunk Merge Queue layers three things on top of that baseline: + + + + + + + + + + + + + +Each links to the deep page with mechanics and worked examples. The rest of this page maps the same three to symptoms you'd recognize on your own team. ## When does this make sense? @@ -57,6 +47,7 @@ Other optimizations worth knowing about: - [**Priority merging**](./optimizations/priority-merging) — fast-track urgent PRs (hotfixes, incident response) to the front of the queue without bypassing it - [**Predictive testing internals**](./optimizations/predictive-testing) — how the foundational mechanic actually works - [**Testing concurrency**](./administration/advanced-settings#testing-concurrency) — how many PRs the queue tests at once +- [**Direct merge to main**](./optimizations/direct-merge-to-main) — skip retesting when a PR is already up to date with `main` and the queue is empty → Full list in [Optimizations](./optimizations/). From bddd92260e17047412a1abc60564d535e9e63918 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 21 May 2026 23:01:08 -0700 Subject: [PATCH 3/5] docs(merge-queue): drop "flake" from anti-flake tile description The tile title is "Anti-flake protection" so "Flakes don't evict PRs." was redundant. "CI gets a second chance." carries the same intuition without the duplicated noun. Co-Authored-By: Claude Opus 4.7 (1M context) --- merge-queue/merge-queue.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/merge-queue/merge-queue.mdx b/merge-queue/merge-queue.mdx index 4c902a1..108e452 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -25,7 +25,7 @@ Trunk Merge Queue layers three things on top of that baseline: From 5ec6e1a5d05a573cd428118dc4d9be0bf4d11827 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Fri, 22 May 2026 00:24:37 -0700 Subject: [PATCH 4/5] docs(merge-queue): promote predictive testing to a 4th tile Adds Predictive testing as a peer tile alongside batching, parallel queues, and anti-flake protection. Layout becomes 2x2. Intro tightened to call out the actual relationship between the mechanics: predictive testing is the correctness baseline; the other three are throughput and resilience optimizations on top of it. The old "three things on top of that baseline" wording overstated the hierarchy - parallel queues is a separate design axis, not strictly derived from predictive testing. Crystal-ball icon for the predictive tile (small wink at "looking ahead" without being too cute). Co-Authored-By: Claude Opus 4.7 (1M context) --- merge-queue/merge-queue.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/merge-queue/merge-queue.mdx b/merge-queue/merge-queue.mdx index 108e452..a4546c9 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -5,9 +5,16 @@ description: "Trunk Merge Queue batches PRs, bisects failures, and routes non-ov A merge queue sits between your developers and your protected branch. Instead of letting PRs merge as soon as their own CI passes, the queue tests each PR against the head of `main` plus every PR ahead of it — so what merges is what was actually tested, even when ten PRs land in the same hour. That predictive testing model is shared across most modern merge queues. -Trunk Merge Queue layers three things on top of that baseline: +Trunk Merge Queue runs on four mechanics. Predictive testing is the correctness baseline; the other three are how Trunk makes it fast and resilient. - + + + + -Each links to the deep page with mechanics and worked examples. The rest of this page maps the same three to symptoms you'd recognize on your own team. ## When does this make sense? From 4b1c96ceb77975b8ea1b6f781088f504dd7ecdc8 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 28 May 2026 16:05:25 -0700 Subject: [PATCH 5/5] docs(merge-queue): lead overview with parallel queues, not batching MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eli flagged the description line ('batches PRs, bisects failures') for leading with two batching-specific features when batching isn't the primary winner. Reframe the page to lead with parallel queues — the direct answer to GitHub MQ's single serial queue and the most-cited real customer win — with anti-flake second and batching last. - Description line now leads parallel queues > anti-flake > batching - Tile grid reordered so batching moves out of the lead-differentiator slot (predictive baseline > parallel > anti-flake > batching) - 'When does this make sense?' leads with the parallel-queues symptom Co-Authored-By: Claude Opus 4.8 (1M context) --- merge-queue/merge-queue.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/merge-queue/merge-queue.mdx b/merge-queue/merge-queue.mdx index a4546c9..512b4e9 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -1,6 +1,6 @@ --- title: "Overview" -description: "Trunk Merge Queue batches PRs, bisects failures, and routes non-overlapping changes into independent test lanes." +description: "Trunk Merge Queue runs unrelated PRs in independent test lanes instead of one serial line, keeps merging when a flaky test would stall the queue, and batches changes to cut CI runs." --- A merge queue sits between your developers and your protected branch. Instead of letting PRs merge as soon as their own CI passes, the queue tests each PR against the head of `main` plus every PR ahead of it — so what merges is what was actually tested, even when ten PRs land in the same hour. That predictive testing model is shared across most modern merge queues. @@ -15,13 +15,6 @@ Trunk Merge Queue runs on four mechanics. Predictive testing is the correctness > - - - + + + ## When does this make sense? -- 50+ PRs/day, CI bill climbing → batching - Monorepo with lanes of work that don't overlap → parallel queues - Flaky tests blocking real merges → anti-flake protection +- 50+ PRs/day, CI bill climbing → batching - Single-track GitHub Merge Queue choking → all three ## More to dial in