From 4286e31b3cc8c6ca61348708d8354a57ab302bf0 Mon Sep 17 00:00:00 2001 From: Stefan Haller Date: Sun, 20 Sep 2026 09:48:18 +0200 Subject: [PATCH] AGENTS.md additions --- AGENTS.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9c3829af1..0dff8780c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,7 +63,9 @@ Prefer a fine-grained commit history. Commits should be as small as possible while still being meaningful and self-contained. - **Every commit must compile and pass all tests.** No "WIP" commits, no - commits that leave the tree broken and rely on a follow-up to fix it. + commits that leave the tree broken and rely on a follow-up to fix it. A + `fixup!` is not such a follow-up; see "Iterate with `fixup!` commits" for + what one may leave broken until it is folded in. - **Every commit must be `gofumpt`-formatted.** Run `just format` before committing. - **Every commit must be lint-clean.** Run `just lint` before committing — @@ -134,6 +136,32 @@ target, make the change, `git commit --fixup=`, then branch. The fixup stays a separate, reviewable commit; only its position changes. +**A fixup may leave commits before it broken until it is folded in.** If a +`fixup!` on an early commit deletes something that a later commit still uses, +the later commit doesn't build until its own `fixup!`, right behind it, catches +up; the same goes for lint. That is expected. The rules above about every +commit compiling, testing and linting clean describe the history *after* +autosquash, and I fold fixups in soon after reviewing them. Never amend a +commit directly, or edit the commits between two fixups, to keep every commit +of the un-squashed history green. The reviewable fixup is worth more than a +green intermediate state. Verify at each fixup instead, since the tree there +is what the folded-in history will have at that point, and say in the handoff +which commits stay broken until which fixup. + +**After a mid-stack fixup, check every branch tip above it, not just the stack +tip.** A fixup that deletes or renames something rewrites every commit replayed +above it, and a commit further up can hide the damage at the tip. A helper +whose last caller the fixup deleted is flagged as unused by `just lint` at the +tip of its own PR, but a later PR that calls it again makes the stack tip lint +clean. Each PR is reviewed and merged on its own, so each PR branch tip has to +be green on its own. After the replay, run `just build`, `just unit-test` and +`just lint` at each branch tip from the insertion point up. If the fixup deleted +or renamed a symbol, also build every replayed commit, for example with +`git -c rebase.autosquash=false rebase -x 'go build ./...' `; +unchanged commits are fast-forwarded, so their hashes stay, and the commits a +fixup is expected to leave broken stop it, so `git rebase --continue` past +those. + If the changes don't map cleanly onto existing commits — say they cut across several of them, or restructure something at a different layer than any existing commit naturally owns — stop and ask the user how to