diff --git a/CLAUDE.md b/CLAUDE.md index 1b0e257..75f69ec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,7 +50,7 @@ When your work is ready for review, you must create a pull request. Do not repor - Push the feature branch to the origin. - If the branch is one reviewable change, submit it via `atgc pr create`. A pull request carries as many commits as the change needed, so this is the usual case even for a long branch. -- If the branch holds several logically separate changes that must be reviewed apart and land in a given order, use `atgc stack create` instead. Mark where each PR ends (`atgc stack mark part1 HEAD~3`), so each PR holds as many commits as its change took; unmarked, it opens one PR per commit. Use `atgc stack sync` for a round of review feedback: it rebases onto the target and reconciles the records in one command. Never `git rebase` a stacked branch, or the marks are left behind. Each PR carries its own screenshots. `atgc stack resubmit` reconciles the chain after any rebase, amend or reorder. +- If the branch holds several logically separate changes that must be reviewed apart and land in a given order, use `atgc stack create` instead. Mark where each PR ends (`atgc stack mark HEAD~3`), so each PR holds as many commits as its change took; unmarked and over three commits, it asks before opening one PR per commit. Use `atgc stack sync` for a round of review feedback: it rebases onto the target and reconciles the records in one command. Never `git rebase` a stacked branch, or the marks are left behind. Each PR carries its own screenshots. `atgc stack resubmit` reconciles the chain after any rebase, amend or reorder. - Post the Tangled PR link for the user to review. When review feedback arrives, submit a new round of work. Follow these steps for each round: diff --git a/README.md b/README.md index 57db32c..906d3d3 100644 --- a/README.md +++ b/README.md @@ -271,13 +271,20 @@ Recorded, not guessed. A branch that merely happens to point into the range — `backup` before a rebase, an old worktree's branch — is not a mark and reshapes nothing. +An unmarked branch of more than three commits is asked about rather than +opened: a pull request per commit is a fine default for two or three and +almost never what anyone meant for eight. Mark the cuts, or say +`--per-commit`, or settle it for the checkout with +`git config stack.perCommit true`. + The `stack` commands are for stacked branches and refuse, pointing at the right `pr` command, when the branch's pull is not stacked; the `pr` commands keep working on stack members, and `pr view` shows the chain when there is one. ``` -atgc stack mark part1 HEAD~3 # cut here: everything below is one PR +atgc stack mark HEAD~3 # cut here; the name comes off that commit +atgc stack mark part1 HEAD~3 # ...or name it yourself atgc stack mark # what is marked, and where each mark sits atgc stack create # push the branch, then a PR per mark # (or per commit, unmarked) diff --git a/src/cmd/agent_notes.txt b/src/cmd/agent_notes.txt index 88fa612..89134c2 100644 --- a/src/cmd/agent_notes.txt +++ b/src/cmd/agent_notes.txt @@ -34,12 +34,12 @@ Stacked pull requests branch holds separate changes that must be reviewed apart and land in order. A stacked PR is not one commit either: mark where each one ends and it holds as many commits as it needs. Unmarked, a stack is one PR - per commit. `stack create` pushes the branch first: every member - records it as the source, and that is how `stack view`, `stack - resubmit` and `stack merge` find the chain again. There is no - --patch-only for a stack. Never run `git rebase` on a stack: it - strands the marks. - atgc stack mark part1 HEAD~3 # cut here; no args lists the marks + per commit; unmarked and over three commits, `create` asks first. + `stack create` pushes the branch first: every member records it as the + source, and that is how `stack view`, `stack resubmit` and `stack + merge` find the chain again. There is no --patch-only for a stack. + Never run `git rebase` on a stack: it strands the marks. + atgc stack mark HEAD~3 # cut here; no args lists the marks atgc stack create # push, then a PR per mark # (--add-change-ids) atgc stack sync # rebase onto main, then reconcile diff --git a/src/cmd/stack/mod.rs b/src/cmd/stack/mod.rs index 847f278..5263ffb 100644 --- a/src/cmd/stack/mod.rs +++ b/src/cmd/stack/mod.rs @@ -370,7 +370,10 @@ pub(crate) enum Command { /// stack mark part1 HEAD~3` records a cut, so everything up to it is one /// pull request and the branch being stacked ends the top one. An /// unmarked branch is one pull request per commit, which is also what - /// `--per-commit` forces when marks exist. All records are written in + /// `--per-commit` forces when marks exist — though past three commits an + /// unmarked branch is asked about first, since a pull request per commit + /// is rarely what somebody meant by eight of them. + /// `git config stack.perCommit true` answers that once per checkout. All records are written in /// one atomic batch. /// /// `atgc stack rebase` replays the branch onto its target and carries