From d4daa0bc4669fa2e3b9e6673b8e3d971e134a67d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 18:47:15 +0000 Subject: [PATCH] Write down the stacked-PR rule that has stranded work twice Merging a PR into a base branch that has already merged puts the work in a branch nobody will merge from again, and GitHub still shows every PR in the stack as merged. It cost the Time chapter rewrite once and the #17/#18 pair before that. Records the rule (retarget onto main before merging the child), the one-line check that proves a branch actually landed, and the verify commands this repository expects before a push. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01ABFpszmPxRorwWtWGR2jXj --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..737b4941 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# Working in this repository + +## Verify before pushing + +Three commands, all of which must pass: + +``` +npm run lint # banned phrases, heading rules, figure and chapter-reference rules +node scripts/check-figure-geometry.mjs # renders every SVG in Chromium: text overlap, arrowheads, coin marks +npm run build-pdf # the whole book, and the page count is a useful smell test +``` + +`npm run preview -- ""` renders a single chapter around a phrase, which is faster than +building the book when checking one edit. + +## Stacked pull requests + +A stacked PR is one whose base is another PR's branch rather than `main`. They have stranded work here +twice, and the failure is silent: GitHub reports every PR in the stack as merged while none of the +content reaches `main`. + +The mechanism: once the parent PR merges, its branch is dead. Merging the child into that dead branch +puts the work somewhere nobody will merge from again. A grandchild stacked on the child inherits the +same fate. + +**Retarget the child onto `main` as soon as the parent merges, and before merging the child.** Do not +merge a PR whose base branch has already merged. + +**After any merge, verify the work actually landed** rather than trusting the merged badge: + +``` +git fetch origin --prune +git merge-base --is-ancestor origin/ origin/main && echo "landed" || echo "STRANDED" +``` + +Prefer a flat PR off `main` whenever the work is separable. Stack only when the child genuinely cannot +be reviewed or built without the parent. + +## Naming things the companion repository owns + +Prose must never name a field, function, or error that does not exist in +`quicknode/solana-program-examples`. When renaming an identifier, the companion repository changes +first and this repository follows, so the book never describes a name that was never shipped. Grep both +repositories before and after: no occurrence of the old name should survive here, and every new name +should resolve to a real definition there. + +## Writing + +`WRITING-PLAN.md` holds the house style and the conventions the linter enforces. Read it before editing +prose.