docs(development): record today's two merge-surfaced bugs and the go-test-cache trap

This commit is contained in:
sam committed 2026-09-26 14:45:41 +10:00
1 parent 4cdc0dc7cb
commit bcafff6941
2 files changed
+18 -1

No files matched your search

+1 -1
View File
@@ -136,7 +136,7 @@
"url": "/dev/development/merging-work/",
"title": "Merging work",
"section": "Development",
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n"
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n4. **A merge can surface a bug neither lane's own tests exposed alone.** Two\n real cases from 2026-09-26: a test that dialled no NATS URL passed on a\n machine with an ambient dev server running and failed the moment it landed\n on a clean CI runner (start an ephemeral server per test, never rely on a\n default port resolving to something); and a cycle-detector that walked a\n Go map in range order reported the same cycle two different ways from run\n to run, invisible until enough fresh (uncached) runs hit the unlucky\n ordering. Both looked like \"the merge broke a passing test\" but were\n latent defects the merge only had the opportunity to expose. Fix the\n defect the failure is pointing at, not the assertion that caught it — see\n CLAUDE.md's test-quality bar before writing the replacement.\n5. `go test`'s cache reuses a package's last result when nothing in its\n dependency graph changed. A merge that touches one package can leave a\n sibling's flaky test silently cached \"pass\" locally while CI runs it\n fresh. `task check` passing on your machine is not proof a merge is\n clean — rerun anything nondeterminism-prone with `-count=1` before\n trusting it, and let CI's from-scratch run be the tiebreaker it is.\n"
},
{
"url": "/dev/development/state-store/",
+17
View File
@@ -27,3 +27,20 @@ passes the same gate.
rule; do not loosen the rule to the test.
3. Run the full suite without `-short`, then `task check`, then commit. Check
`git status` for files a test wrote into the tree before staging.
4. **A merge can surface a bug neither lane's own tests exposed alone.** Two
real cases from 2026-09-26: a test that dialled no NATS URL passed on a
machine with an ambient dev server running and failed the moment it landed
on a clean CI runner (start an ephemeral server per test, never rely on a
default port resolving to something); and a cycle-detector that walked a
Go map in range order reported the same cycle two different ways from run
to run, invisible until enough fresh (uncached) runs hit the unlucky
ordering. Both looked like "the merge broke a passing test" but were
latent defects the merge only had the opportunity to expose. Fix the
defect the failure is pointing at, not the assertion that caught it — see
CLAUDE.md's test-quality bar before writing the replacement.
5. `go test`'s cache reuses a package's last result when nothing in its
dependency graph changed. A merge that touches one package can leave a
sibling's flaky test silently cached "pass" locally while CI runs it
fresh. `task check` passing on your machine is not proof a merge is
clean — rerun anything nondeterminism-prone with `-count=1` before
trusting it, and let CI's from-scratch run be the tiebreaker it is.