From f8fbef7b43fa6f1bccb3a7d75e7ff7888039737e Mon Sep 17 00:00:00 2001 From: Mehdi ABAAKOUK Date: Mon, 1 Jun 2026 16:37:35 +0200 Subject: [PATCH] docs(merge-queue): disambiguate parallel checks from parallel mode Both features carry the word "parallel" but are orthogonal, which reads as a conflict. Lead the Parallel Checks page with "speculative" (the term the API and activity log already use) and add mirror disambiguation notes on Parallel Checks and Queue Modes: parallel checks are speculative CI within a single ordered queue, parallel mode is scope-based independent queues, and the two compose. Also repoint two stale /merge-queue/parallel-scopes links to the renamed queue-modes page. Change-Id: Id0ac2739191e4984293c3d970ebdbad5d5b3ba92 --- .../docs/merge-queue/parallel-checks.mdx | 28 +++++++++++++------ src/content/docs/merge-queue/queue-modes.mdx | 7 +++++ 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/src/content/docs/merge-queue/parallel-checks.mdx b/src/content/docs/merge-queue/parallel-checks.mdx index a5712efe65..878c93bb31 100644 --- a/src/content/docs/merge-queue/parallel-checks.mdx +++ b/src/content/docs/merge-queue/parallel-checks.mdx @@ -6,16 +6,26 @@ description: Accelerates the merging process by testing the compatibility of mul import { Image } from "astro:assets" import specChecksListScreenshot from "../../images/merge-queue/parallel-checks/spec-checks-list.png" -Parallel Checks let Mergify test multiple queued pull requests together so you -ship faster. Mergify creates temporary batch PRs that represent cumulative -merges (PR#1), (PR#1+PR#2), (PR#1+PR#2+PR#3), runs CI on them in parallel, then -merges the original PRs once checks pass. +Parallel checks are how Mergify tests the queue **speculatively**: instead of +validating one pull request at a time, it tests several queued pull requests +ahead of time so you ship faster. Mergify creates temporary batch PRs that +represent cumulative merges (PR#1), (PR#1+PR#2), (PR#1+PR#2+PR#3), runs CI on +them in parallel, then merges the original PRs once checks pass. The +`max_parallel_checks` setting controls how far ahead it tests. :::tip Learn how speculative checks work conceptually at the [Merge Queue Academy](https://merge-queue.academy/features/speculative-merging/). ::: +:::note + Parallel checks are not the same as **parallel mode**. Parallel checks are + speculative CI that speed up any single ordered queue, in serial or parallel + mode alike. [Parallel mode](/merge-queue/queue-modes) is a separate choice + about whether independent [scopes](/merge-queue/scopes) form independent + queues. The two are configured separately and work together. +::: + ## How Parallel Checks Work Mergify groups PRs by their position in the queue and the `max_parallel_checks` @@ -126,7 +136,7 @@ to match your CI capacity and typical PR size/complexity. ## When Things Change -Parallel Checks adapt automatically as your code and rules evolve: +Parallel checks adapt automatically as your code and rules evolve: - Failed checks: Mergify removes the failing PR and continues with the rest. @@ -246,7 +256,7 @@ increase concurrency; choose a value your CI can handle reliably. For deeper guidance and trade‑offs (including batching), see [Merge queue performance](/merge-queue/performance). -In [parallel mode](/merge-queue/parallel-scopes), you can also cap concurrency -for an individual scope while leaving the rest free to use the global ceiling. -See [Limiting concurrency per -scope](/merge-queue/parallel-scopes#limiting-concurrency-per-scope). +In [parallel mode](/merge-queue/queue-modes#parallel-mode), you can also cap +concurrency for an individual scope while leaving the rest free to use the +global ceiling. See [Limiting concurrency per +scope](/merge-queue/queue-modes#limiting-concurrency-per-scope). diff --git a/src/content/docs/merge-queue/queue-modes.mdx b/src/content/docs/merge-queue/queue-modes.mdx index eae7e1da52..c6772c36b5 100644 --- a/src/content/docs/merge-queue/queue-modes.mdx +++ b/src/content/docs/merge-queue/queue-modes.mdx @@ -82,6 +82,13 @@ together so they are tested as a group, preventing semantic conflicts. serial mode may be a better fit. ::: +:::note + Parallel **mode** is not the same as [parallel checks](/merge-queue/parallel-checks). Parallel + mode is about **scopes**: independent queues that don't wait on each other. Parallel checks are + **speculative** CI that test queued pull requests ahead of time within a single ordered queue, + and they run in serial mode too. The two are configured separately and work together. +::: + Batches that share no scope run at the same time: ```dot class="graph"