docs: Pages site cleanup step 1 - curated publish set + cross-link fixes (#51)

* docs: step 1 of the docs/site cleanup - whitelist Pages site config, fix cross-links to excluded docs, drop game-behavior-reference index bullet

Publish only the curated set (index/building/internals/porting-notes/
dev-process/agentic-development); everything else under docs/ stays in
the repo but out of the Pages build and sitemap. Cross-links from the
published pages to excluded docs now point at GitHub blob URLs so they
still resolve. No content rewrite yet -- steps 2-5 (README update, per-
page descriptions, light copy passes, repo hygiene) remain.

Claude-Session: https://claude.ai/code/session_016TaKy6AAsVUTfjkhrX6CjG

* docs(dev-process): add §6 -- keep PR/git-history noise low

Squash-merge single-purpose/docs PRs, batch same-session docs updates
into one branch instead of one-PR-per-finding, keep unrelated
housekeeping off active branches, declare stacked-PR dependencies, and
triage the open-PR list every session -- close stale PRs (superseded
by newer main content) rather than force-merging or endlessly
rebasing them.

Prompted by this session's PR #26: real conflicts against main because
D191/D193/D149 were all fixed/closed since it was opened; closed
rather than rebased.
This commit is contained in:
James Dansereau authored and GitHub committed 2026-09-11 17:31:36 -04:00
1 parent b577008543
commit 4d45e78176
7 files changed
+94 -33

No files matched your search

+40 -1
View File
@@ -41,7 +41,8 @@ more room.
Lewis's agents recorded generalisable IDO quirks in a learnings file; later
agents read it and did better. Our equivalent is
[`porting-notes.md`](porting-notes.md) — the recurring N64→PC bug classes,
each entry a terse index into the full [`dev/findings.md`](dev/findings.md)
each entry a terse index into the full
[`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md)
log. Every investigation brief links it, and every investigation ends by
appending any new generalisable quirk.
@@ -91,6 +92,44 @@ Then hand the agent the *findings*, not just the problem.
inverted here — the hard part is identifying the implicit hardware/ABI
contract the already-readable C depends on.
## 6. Keep PR/git-history noise low
A session produces a lot of small, independently-verifiable units of work —
one Dxx row, one docs pass, one mechanical fix. Left unmanaged that turns
into a pile of small open PRs that's harder to review than the work
justifies. Rules:
- **Squash-merge single-purpose and docs-only PRs.** The repo has squash
merge enabled; use it (`gh pr merge --squash --delete-branch`) for anything
whose in-branch commit history (iteration, probe-add, probe-strip) isn't
itself useful to keep — which is most PRs. Reserve a plain merge commit for
a PR whose individual commits are each a distinct, reviewable unit someone
might want to `git revert` independently (e.g. this session's PR #50: a
fix commit + a separate analysis-only commit).
- **Batch same-session, same-flavor docs updates into one PR/branch**
instead of opening a new PR per finding row. A runtime re-check that
updates one `findings.md` row (like #48) doesn't need its own PR if
another docs-only branch is already open in the same session — fold it in.
Only split into separate PRs when the pieces have genuinely different
review/merge timing (e.g. one needs a human playtest, the other doesn't).
- **A branch takes only the change it's named for.** Don't let unrelated
housekeeping (a stray gitignore fix, a config tweak) ride along on an
active feature/fix branch just because it's the one checked out — cut a
separate branch, even for a one-line change.
- **Stacked PRs declare the dependency in the title/body** ("step 2 of N,
step 1 is #N") and get rebased/merged in order promptly — don't let a
later step sit open so long the earlier step's content drifts under it.
- **Triage the open-PR list at least once a session**, ordered by
time-to-close (docs-only and non-draft first, human-playtest-gated last).
A PR idle long enough that `main` has moved past the finding rows it
touches is **stale, not just old** — check for real textual conflict
(`git merge-tree`), not just calendar age. If `main` already has more
current information than the PR (a bug the PR still lists `OPEN` that's
since been fixed and verified), **close it rather than force a merge or
spend a cycle rebasing it** — re-derive only whatever part of its content
is still true as a fresh, small PR against current `main`. Merging stale
content back over newer information is a regression, not a save.
## Investigation-brief template
```