docs(merge-queue): reframe migrate-from-github around same-day switch

[samgutentag]

Summary

Reframes merge-queue/migrating-from-github-merge-queue.md around a clean same-day switch as the recommended path. The original page presented "Running both merge queues simultaneously" as a common, low-risk option, which Robert Eperjesi and Eli Schleifer pushed back on in the #cs-klaviyo thread: long-term dual mode means in-flight PRs from both queues preempt each other and slows merges for everyone.

Triggered by Klaviyo evaluating a pilot where some teams ran Trunk while others stayed on GitHub Merge Queue, and Matt flagging that the docs didn't make the recommended path clear.

The three patterns this page now distinguishes

Pattern	How the page treats it
A — Clean same-day switch	Default recommended path. 4-step admin runbook (set up Trunk → disable GH queue → turn on Trunk's PR comments → announce).
B — Admin-driven validation first	Smaller "Cautious route" section for teams that want to confirm settings on a few real PRs before switching. Most PRs continue through GH queue; admin manually invokes /trunk merge on a handful.
Anti-pattern: long-term dual mode	A single warning callout at the top: "Don't run both queues for an extended period." No further endorsement.

What changed

• New 4-step Migration steps section (Pattern A) replaces the original mix of "Turn off GitHub Merge Queue" / "Enable Trunk Merge Queue" / "Running both merge queues simultaneously" / "Pre-migration" sections.
• New Cautious route: validate first section (Pattern B) captures the legitimate use case for brief overlap (admin testing on a few PRs).
• The "Trunk Handles External Merges Gracefully" claim is kept but moved into the Cautious route section as a safety net for accidental collisions during validation, not as a feature that enables long-term coexistence. Verified against code in trunk/services/merge/src/controller/graph_controller.ts (manualPushToTargetBranch, transitionAllNodesToPendingDueToManualPush).
• Added Dev-facing announcement copy admins can paste into Slack or email. Matt explicitly asked for this in the thread.
• Top-of-page warning callout against long-term dual mode replaces the old "Running both merge queues simultaneously" section.

What did not change

• summary.md (no nav change; same page, same path).

Engineering reviewers

• Robert Eperjesi (Merge Queue co-owner; Sam to tag with correct GitHub handle)
• Phil Vendola (Merge Queue owner)

Context links

• Klaviyo pilot thread: https://trunk-io.slack.com/archives/C09L0GB2771/p1778860519234699
• Robert's narrowing message: https://trunk-io.slack.com/archives/C09L0GB2771/p1779121294557489?thread_ts=1778860519.234699
• Eli's "they'll have bad experience" message: https://trunk-io.slack.com/archives/C09L0GB2771/p1778861171296799?thread_ts=1778860519.234699

Test plan

• Open the GitBook change request preview and verify all internal links resolve.
• Verify section anchors render (#cautious-route-validate-first, #dev-facing-announcement-copy).
• Confirm the warning hint and info hints render correctly in GitBook.

🤖 Generated with Claude Code

[trunk-staging-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[claude]

Claude finished @samgutentag's task in 2m 13s —— View job

---

Review summary

• Read the changed file
• Check for typos, grammar, and formatting
• Review documentation best practices
• Post review feedback

No blocking issues found. The rewrite into a 4-step runbook is a clear improvement — the new top-of-page warning hint scopes dual mode appropriately, the "Why complete the migration" subsection gives admins the reason behind the recommendation, and the announcement template lowers the friction for admins to roll the change out.

Posted 4 non-blocking inline nits:

1. repo vs repository (lines 37–39) — bullet list says "your repo's CI" / "for your repo" while the rest of this page and neighboring docs (getting-started/README.md) use "repository". Suggested edit included.
2. Section intro fragment (line 23) — "The recommended sequence for admins moving a repository…" is a fragment; a complete sentence would match the rest of the page's style.
3. Placeholder formatting (lines 84–88) — template mixes `[repo]` (backticks) with \[date], \[admin contact], \[link…] (escaped). Suggest picking one style; backticks render as monospace and read more clearly as "fill this in".
4. Blockquote vs code block (lines 82–88) — the announcement template is in a blockquote; a fenced code block would make it a one-click copy in GitBook. Stylistic call.

Things I verified and that look good:

• Anchor links resolve to real headings: #why-complete-the-migration → line 68, #what-happens-during-dual-mode → line 59, #dev-facing-announcement-copy → line 78.
• Relative paths getting-started/, using-the-queue/, administration/advanced-settings.md all exist.
• Hint styles (success, warning, info) are used consistently with the rest of merge-queue/.
• The "Trunk Handles External Merges Gracefully" claims (lines 61–66) were preserved and reframed as "What happens during dual mode" — matches the PR description's intent.
• GitBook escape conventions (*** rules, **bold UI path** segments, \[placeholder] escapes) are consistent with the rest of the page.
  • sam-gutentag/mq-migrate-from-github-runbook

[claude]

Nit (consistency): This bullet list uses "repo" twice (your repo's CI, for your repo), but the rest of this page and neighboring docs (merge-queue/getting-started/README.md) consistently use "repository". Recommend matching the surrounding style.

Suggested change

	* Branch protection rules trigger the required checks you expect.
	* Test orchestration policies match your repo's CI.
	* [Advanced settings](administration/advanced-settings.md) such as timeouts, batching, and optimistic merging behave correctly for your repo.
	* Branch protection rules trigger the required checks you expect.
	* Test orchestration policies match your repository's CI.
	* [Advanced settings](administration/advanced-settings.md) such as timeouts, batching, and optimistic merging behave correctly for your repository.

[claude]

Nit (placeholder formatting): Placeholders mix two styles in the template — [repo] is in backticks while [date], [link to Trunk's Using the Queue page], and [admin contact] use the escaped form \[...]. For a copy/paste template, picking one style makes it easier for admins to spot what they need to replace. Backticks render as monospace in GitBook, which is the stronger visual cue that "this is a placeholder you must fill in" — consider using them for all four. (Non-blocking.)

[claude]

Nit (style): This is a sentence fragment functioning as a section intro. Reads slightly off compared to the rest of the page which uses complete sentences. Consider:

Suggested change

	The recommended sequence for admins moving a repository from GitHub Merge Queue to Trunk Merge Queue.
	Follow this sequence to move a repository from GitHub Merge Queue to Trunk Merge Queue.

Non-blocking.

[claude]

Consider: This template is rendered as a Markdown blockquote, which is good for visual separation but means an admin copying the rendered text from GitBook may need to strip the indentation/styling depending on their browser's copy behavior. A fenced code block (no language) would make the template a one-click copy in GitBook's UI. Up to you — blockquote is fine if you prefer the inline-prose look.

[github-actions]

Auto-approved: Claude code review passed.

[claude]

Claude finished @samgutentag's task in 1m 52s —— View job

---

Review summary

• Read the changed file
• Diff against origin/main to see what's new since last review
• Check for typos, grammar, and formatting
• Verify links and anchors
• Post review feedback

No blocking issues. The latest rewrite (commit 3f6eefb) is a meaningful improvement on the prior structure: the clean same-day switch is now the headlined path, the "Cautious route: validate first" demotes dual mode appropriately, and the "Trunk Handles External Merges Gracefully" claims are reframed inside the cautious route as a safety net for accidental collisions — exactly the framing the Klaviyo thread asked for.

Verified

• All anchors resolve: #dev-facing-announcement-copy → line 71. ✓
• No stale references in the repo to removed anchors #what-happens-during-dual-mode / #why-complete-the-migration (checked across **/*.md). ✓
• summary.md:15 still points at the page path, no nav change required. ✓
• Relative paths (getting-started/, administration/advanced-settings.md, using-the-queue/) all exist. ✓
• Hint styles (success, warning, info) consistent with the rest of merge-queue/. ✓

Non-blocking nits (carryovers from prior review + new)

1. repo vs repository (line 28) — carryover. The bullet list that previously had your repo's CI / for your repo is gone, but one instance remains: "...optimistic merging for your repo." Suggest "for your repository" for consistency with the rest of the page.

2. Section intro fragment (line 24) — carryover. "The recommended sequence for admins moving a repository from GitHub Merge Queue to Trunk Merge Queue." is still a fragment. A complete sentence (e.g. "Follow this sequence to move a repository from GitHub Merge Queue to Trunk Merge Queue.") would match the rest of the page's voice.

3. Placeholder formatting mix (lines 77–81) — carryover. Template still mixes `[repo]` (backticks) with \[date], \[link to Trunk's Using the Queue page], \[admin contact] (escaped). Picking one style helps admins scan for "fill this in" — backticks render as monospace in GitBook and read more clearly.

4. Blockquote vs code block (lines 75–81) — carryover, stylistic. A fenced code block would make the announcement template a one-click copy in GitBook. Blockquote is fine if you prefer the prose look.

5. Minor phrasing (line 52) — new. "...run a short validation window before doing step 2 above." — "before doing step 2 above" reads slightly awkward. Could simplify to "...before step 2."

Fix carryover nits →
• sam-gutentag/mq-migrate-from-github-runbook

[github-actions]

Auto-approved: Claude code review passed.

[samgutentag]

Verification status (2026-05-18): live

Verified: customers can use this. Ready to publish.

Notes on the verification:

• This PR is a structural rewrite of existing-feature documentation, not new-feature docs. The feature being documented (the migration path from GitHub Merge Queue to Trunk Merge Queue) has been live as long as Trunk Merge Queue has shipped.
• No engineering PR refs in the body and no Linear ticket. The standard verify workflow (eng PR → flag → rollout signals) does not apply here.
• Code claims in the PR body were verified earlier against actual source in trunk/services/merge/src/controller/graph_controller.ts:
  • manualPushToTargetBranch (lines 1553-1728): classifies external commits and routes to mark-merged or restart paths.
  • transitionAllNodesToPendingDueToManualPush (lines 1491-1548): the restart path described in the "Safety net" callout.
• Eng PR: none referenced (rewrite of existing docs)
• Flag: none (no gated feature)
• Signals checked: code source for the safety-net claims kept on the page

Next action: standard docs review (copy, anchors, GitBook preview). Two prior Claude reviews on this PR have logged non-blocking nits that are worth addressing before ready-for-review.

[samgutentag]

Closing — Sam will handle this migration to docs2 manually. The reframe (clean same-day switch as the default, Klaviyo Slack rationale) is still the intended direction; tracking outside this PR.