docs(merge-queue): clarify stacks override scope/file similarity in batching

[sileht]

The batch-grouping section listed priority, scopes, changed directories,
and queue time as the similarity ranking, then described stacks in a
separate paragraph that read as a fifth tier of that order. Readers
(jd on PR #11693) took it as "scope -> files -> stack" and expected
stack to come before files.

Reframe the stack rule to match the engine: in serial mode stack
co-location is a separate constraint outside the similarity ranking
(_add_pull_with_predecessors), not a ranking tier. Selected pull
requests drag their queued predecessors into the same batch regardless
of scope or directory overlap, so stack relationships take precedence
over scope and directory similarity, bounded only by batch_size.

Also repoint the stale parallel-scopes link to queue-modes#parallel-mode.

Fixes MRGFY-7466

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 🤖 Continuous Integration

Wonderful, this rule succeeded.

• all of:
  • check-success = build
  • check-success = lint
  • check-success = test
  • any of:
    • check-success = test-broken-links
    • label = ignore-broken-links
  • any of:
    • check-success=Cloudflare Pages
    • -head-repo-full-name~=^Mergifyio/

🟢 👀 Review Requirements

Wonderful, this rule succeeded.

• any of:
  • #approved-reviews-by >= 2
  • author = dependabot[bot]
  • author = mergify-ci-bot

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?:

🟢 🔎 Reviews

Wonderful, this rule succeeded.

• #changes-requested-reviews-by = 0
• #review-requested = 0
• #review-threads-unresolved = 0

🟢 📕 PR description

Wonderful, this rule succeeded.

• body ~= (?ms:.{48,})

[Copilot]

Pull request overview

This PR clarifies how merge-queue batching works in serial mode by explicitly separating the similarity ranking (priority/scopes/directories/queue time) from the stack-co-location constraint, so readers don’t misinterpret stacks as an additional “fifth tier” that comes after file similarity.

Changes:

• Updates the parallel-mode reference to point to Queue Modes → Parallel Mode instead of the stale /merge-queue/parallel-scopes link.
• Adds explicit wording that the similarity ranking applies only to independent PRs, and that stack dependencies are handled by a separate rule that overrides similarity.
• Rewrites the “Stacks stay together” section to state that predecessors are pulled into the same batch regardless of scope/directory overlap, bounded by batch_size.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sileht]

Revision history

#	Type	Changes	Reason	Date
1	initial	f765079		2026-06-02 08:23 UTC
2	content	f765079 → ec8ee0c (raw)		2026-06-02 08:23 UTC

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-06-02 09:20 UTC · Rule: default
• ✅ Checks passed · on draft merge queue: embarking main (5073dc5) and #11702 together #11703
• ✅ Merged — 2026-06-02 09:23 UTC · at ec8ee0cbb095c09a36ec6a13c00781eb54da5e4c · squash

This pull request spent 2 minutes 17 seconds in the queue, including 1 minute 50 seconds running CI.

Required conditions to merge

• schedule=Mon-Fri 09:00-17:30[Europe/Paris]
• all of [🛡 Merge Protections rule Enforce conventional commit]:
  • title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?:
    • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
• all of [🛡 Merge Protections rule 👀 Review Requirements]:
  • any of:
    • #approved-reviews-by >= 2
      • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
    • author = dependabot[bot]
      • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
    • author = mergify-ci-bot
      • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
• all of [🛡 Merge Protections rule 📕 PR description]:
  • body ~= (?ms:.{48,})
    • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
• all of [🛡 Merge Protections rule 🔎 Reviews]:
  • #changes-requested-reviews-by = 0
    • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
  • #review-requested = 0
    • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
  • #review-threads-unresolved = 0
    • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
• all of [🛡 Merge Protections rule 🤖 Continuous Integration]:
  • all of:
    • check-success = build
    • check-success = lint
    • check-success = test
    • any of:
      • check-success = test-broken-links
      • label = ignore-broken-links
        • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702
    • any of:
      • check-success=Cloudflare Pages
      • -head-repo-full-name~=^Mergifyio/
        • docs(merge-queue): clarify stacks override scope/file similarity in batching #11702