From 4d45e78176366b0814fe32cc7e81eeaeda864ab3 Mon Sep 17 00:00:00 2001 From: James Dansereau <106631954+jkdansereau@users.noreply.github.com> Date: Fri, 11 Sep 2026 17:31:36 -0400 Subject: [PATCH] docs: Pages site cleanup step 1 - curated publish set + cross-link fixes (#51) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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. --- docs/_config.yml | 64 +++++++++++++++++++++------------ docs/building.md | 8 ++--- docs/dev-process.md | 41 ++++++++++++++++++++- docs/dev/agentic-development.md | 5 +-- docs/index.md | 1 - docs/internals.md | 5 +-- docs/porting-notes.md | 3 +- 7 files changed, 94 insertions(+), 33 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 7823e111..c3e3f377 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -3,8 +3,8 @@ title: GoldenEye 007 PC Port description: >- A native PC port of the original Nintendo 64 GoldenEye 007, built from its - decompiled source, and a case study in AI-agent collaboration on a large - low-level codebase. + decompiled source with a software RSP — plus the engineering record: + internals, porting notes, and the two-agent development workflow. theme: jekyll-theme-cayman show_downloads: false @@ -26,26 +26,46 @@ plugins: - jekyll-sitemap # jekyll-relative-links (on by default for Pages) rewrites the .md links in -# these docs to .html so cross-links work on the published site. +# these docs to .html so cross-links work on the published site. Links that +# must reach docs kept out of the site build point at the GitHub blob URL +# instead, so they resolve from the published pages too. -# Rolling local working files - not useful as published pages. +# --------------------------------------------------------------------------- +# The site publishes a small curated set (see docs/dev/notes/DE-SLOP-DOCS-PLAN.md): +# index.md, building.md, internals.md, porting-notes.md, dev-process.md, +# dev/agentic-development.md +# Everything else under docs/ is working material - the finding log, level +# status, backlogs, plans, inherited decomp guides. It stays in the repo (and +# on GitHub) but is excluded from the site build so it never shows up as a +# published page or in sitemap.xml. exclude: + - BACKLOG.md - HANDOFF.md - -# Keep the raw engineering record (finding log, per-level status, triage -# notes, backlogs) out of sitemap.xml so search engines aren't steered at it. -# The pages still build and stay reachable from cross-links; the two dev/ -# docs that are linked from the site index are kept in. -defaults: - - scope: - path: "dev" - values: - sitemap: false - - scope: - path: "dev/agentic-development.md" - values: - sitemap: true - - scope: - path: "dev/game-behavior-reference.md" - values: - sitemap: true + - SetupGuide.md + - StructureGuide.md + - StyleGuide.md + - dev/AUDIO-PLAN.md + - dev/AUDIT-M6-player-offsets.md + - dev/D172-PARTICLE-COLOR-RESEARCH.md + - dev/D176a-SKY-NOTES.md + - dev/GE-ENV-PROBES.md + - dev/GRAPHICS-BACKLOG.md + - dev/HANDOFF-ARCHIVE.md + - dev/LEVEL-OBJECTIVES.md + - dev/LEVEL-PLAYTEST.md + - dev/LEVEL-STATUS.md + - dev/LINUX-PORT.md + - dev/M-35-PLAYTEST-CHECKLIST.md + - dev/M-35-QOL-REVIEW.md + - dev/M-36-TRIAGE.md + - dev/MODERN-PORT-FEATURES-BACKLOG.md + - dev/OPTIONS-MENU-PLAN.md + - dev/QOL-INVENTORY.md + - dev/TEXTURE-GLITCH-ANALYSIS.md + - dev/UNLOCKED-FPS-PLAN.md + - dev/VIEWMODEL-RESEARCH.md + - dev/WIDESCREEN-FOV-PLAN.md + - dev/findings-index.csv + - dev/findings.md + - dev/game-behavior-reference.md + - dev/release-dropin-rom-plan.md diff --git a/docs/building.md b/docs/building.md index 760d38f0..890fccf3 100644 --- a/docs/building.md +++ b/docs/building.md @@ -43,9 +43,9 @@ binutils), `make`, `git`, and `python3`. They build a small host-compiled `tools/extractor` and slice blobs straight out of the ROM — **no IDO / IRIX toolchain is involved in extraction or in the PC build.** (The IDO toolchain is only needed to build the N64 ROM itself, and its proprietary SGI binaries are -not distributed here — see [`SetupGuide.md`](SetupGuide.md) "Recompile IDO".) +not distributed here — see [`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md) "Recompile IDO".) On Windows this is easiest under WSL or a Linux VM. Full details and -alternatives (Docker) are in [`SetupGuide.md`](SetupGuide.md). +alternatives (Docker) are in [`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md). --- @@ -70,7 +70,7 @@ and run: (US extraction is a prerequisite for the others.) This populates `assets/` with the generated `.bin` blobs the build needs. See -[`SetupGuide.md`](SetupGuide.md) for the in-depth build/asset pipeline. +[`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md) for the in-depth build/asset pipeline. --- @@ -158,4 +158,4 @@ runtime. `ge007.ini` is written under `data/` on first launch. | `GE_PCDUMP="first-last:step"` | dump rendered frames as PPM (debugging) | More diagnostic switches are cataloged in -[`dev/GE-ENV-PROBES.md`](dev/GE-ENV-PROBES.md). +[`dev/GE-ENV-PROBES.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GE-ENV-PROBES.md). diff --git a/docs/dev-process.md b/docs/dev-process.md index 35664b35..da406ae8 100644 --- a/docs/dev-process.md +++ b/docs/dev-process.md @@ -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 ``` diff --git a/docs/dev/agentic-development.md b/docs/dev/agentic-development.md index 67bc71a5..29155a70 100644 --- a/docs/dev/agentic-development.md +++ b/docs/dev/agentic-development.md @@ -106,7 +106,7 @@ issues still outstanding. |---|---| | Calendar time | 16 days (16 Aug – 1 Sep 2026), one person part-time | | Commits on the port | ~223 | -| Root-caused bugs logged | 162 (`D1`–`D169` in [`findings.md`](findings.md); some later merged or withdrawn) | +| Root-caused bugs logged | 162 (`D1`–`D169` in [`findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md); some later merged or withdrawn) | | Handoff sessions | ~33 (`M-2` … `M-33`) | | Game-source files given `#ifdef PORT` ABI edits | 63 files, 241 blocks | | New port-layer / tooling files | 128 | @@ -261,4 +261,5 @@ Honest notes, for anyone weighing whether this transfers. **Still outstanding** (parked below crash/level work): audio is not implemented; several front-end 3D transforms and some text rendering are -wrong. See [`GRAPHICS-BACKLOG.md`](GRAPHICS-BACKLOG.md). +wrong. See +[`GRAPHICS-BACKLOG.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GRAPHICS-BACKLOG.md). diff --git a/docs/index.md b/docs/index.md index 3ea48874..b0ad9b43 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,5 +30,4 @@ and cutscenes are rough. - **[Development process](dev-process.md)** — how work was scoped, partitioned, and budgeted across agents; the finding-log discipline. - **[Internals](internals.md)** — architecture, the software RSP-emulation approach, GoldenEye-vs-Perfect-Dark engine differences, the phased plan. - **[Porting notes](porting-notes.md)** — the recurring Nintendo 64 → PC bug classes hit during the port, with fixes. -- **[Game-behavior reference](dev/game-behavior-reference.md)** — how the retail N64 game is meant to behave: combat/AI model, difficulty scaling, per-level objectives, timers, weapon data, and the original game's known quirks. - **[Building](building.md)** — full build and asset-extraction guide. diff --git a/docs/internals.md b/docs/internals.md index 5ebeab82..885876d1 100644 --- a/docs/internals.md +++ b/docs/internals.md @@ -5,8 +5,9 @@ > external references. The phased plan in section 8 is largely done through > Phase 2 — for current status see the > [README](https://github.com/jkdansereau/goldeneye-pc-port#status) and -> [`dev/LEVEL-STATUS.md`](dev/LEVEL-STATUS.md); for the blow-by-blow finding -> log see [`dev/findings.md`](dev/findings.md). +> [`dev/LEVEL-STATUS.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/LEVEL-STATUS.md); +> for the blow-by-blow finding log see +> [`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md). This document captures the research done to plan a PC port of GoldenEye 007, based on the decompilation this repository is forked from diff --git a/docs/porting-notes.md b/docs/porting-notes.md index 0d3d8c18..faa81ed0 100644 --- a/docs/porting-notes.md +++ b/docs/porting-notes.md @@ -4,7 +4,8 @@ A field guide to the bug classes that keep recurring when running big-endian 32-bit N64 game code, unmodified, on a little-endian 64-bit host. Terse by design — each entry compresses a full investigation to a symptom, a fix, and a grep heuristic for finding siblings. Each entry cites a `Dxx` label; the full -evidence and fix for that instance live in [`dev/findings.md`](dev/findings.md) +evidence and fix for that instance live in +[`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md) under the same label. Skim the section headers; read the classes relevant to the task at hand.