From acf22259c374b7d4c1de946478be3c85a299971a 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 9fee52d..21bc2c9 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -1,74 +1,70 @@ --- 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." og:title: "Trunk Merge Queue overview" --- -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 5d711e06f1adbdec0ba55f2ddda86f53d4301de4 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 21bc2c9..230633d 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -6,43 +6,33 @@ og:title: "Trunk Merge Queue overview" 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? @@ -58,6 +48,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 07425fef35a7ada1bac12fe9ae397889950c8b78 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 230633d..82b2fb6 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -26,7 +26,7 @@ Trunk Merge Queue layers three things on top of that baseline: From 1496e9e3ec75afdb3283f258b07b71b8b90f53aa 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 82b2fb6..6c858b0 100644 --- a/merge-queue/merge-queue.mdx +++ b/merge-queue/merge-queue.mdx @@ -6,9 +6,16 @@ og:title: "Trunk Merge Queue overview" 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 8a0da70b8ec97d8536c81d517bd0d62fe7e1d23e 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 6c858b0..a7a95d2 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." og:title: "Trunk Merge Queue overview" --- @@ -16,13 +16,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