mirror of
https://github.com/jkdansereau/goldeneye-pc-port.git
synced 2026-10-23 15:52:42 +02:00
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:
1 parent
b577008543
commit
4d45e78176
7 files changed
+94
-33
No files matched your search
+40
-1
@@ -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
|
||||
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user