From a859305a7fd45888a4e8c5c6c4955b4d3ccc7cd9 Mon Sep 17 00:00:00 2001
From: Vadim Zolotokrylin <1125014+zolotokrylin@users.noreply.github.com>
Date: Fri, 9 Oct 2026 22:20:11 +0800
Subject: [PATCH] docs(rules): merge a stack in one step with gh stack merge

---
 docs/rules/DEV-325.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/rules/DEV-325.md b/docs/rules/DEV-325.md
index dbf20c7..499361c 100644
--- a/docs/rules/DEV-325.md
+++ b/docs/rules/DEV-325.md
@@ -25,7 +25,10 @@ one it depends on, and GitHub shows them as one stack.
    `sync`), not by retargeting branches by hand.
 1. In each PR description, say what it is stacked on and what it adds, so a
    reader follows the stack bottom to top. A PR that nothing calls yet says so.
-1. Merge the stack in order, bottom first.
+1. Merge with `gh stack merge`, which merges every PR up to the one you choose
+   in a single step, bottom first. Merging one PR at a time from the GitHub page
+   forces a rebase of every PR above it: the squash merge writes a new commit,
+   and the branches above still carry the original ones.
 
 Good: "Stacked on the calculation PR. Turns logged hours into the markdown the
 command will post; nothing calls it yet." Bad: five PRs opened against the
@@ -38,4 +41,4 @@ other four.
       the default branch
 - [ ] The Spec PR, when there is one, sits at the bottom of the stack
 - [ ] Each PR description says what it is stacked on and what it adds
-- [ ] The stack merges bottom first
+- [ ] The stack merges bottom first, with `gh stack merge`