From 8477ea698b081d8ed569c64836c3933ad4702506 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Sun, 2 Aug 2026 22:01:27 -0400 Subject: [PATCH] Repoint every stale TODO.md citation in the tree A sweep of all 265 tracked files, not just the ones the migration touched. Two cross-repository citations named deps/libakerror/TODO.md item 8, a numbering that has not existed for two releases; both now name libakerror issue #18. Three tutorial and plan references pointed at TODO.md for defects that are tracked: the invisible-on-frame-one actor is #39, the control map traps are #81, and the pkg-config gap is #17. plan.md is a live instruction document for writing the manual and still told its reader to file findings in TODO.md; it says the tracker now. Filed while sweeping: a zeroed akgl_ControlMap matches gamepad South, because SDL_GAMEPAD_BUTTON_SOUTH is 0 and the two arms of the match are one expression, and handler_on/handler_off are called without a NULL check. Both are documented as workarounds in chapter 21 and neither had an issue. #81. Co-Authored-By: Claude Opus 5 (1M context) Co-Authored-By: Andrew Kesterson --- AGENTS.md | 4 ++-- CMakeLists.txt | 2 +- docs/20-tutorial-sidescroller.md | 3 +-- docs/21-tutorial-jrpg.md | 4 ++-- plan.md | 16 ++++++++-------- 5 files changed, 14 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bdc8c4f..396927e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -297,8 +297,8 @@ backend vtable entry or an SDL callback must match a signature whether it reads every argument or not, and 4 `-Wimplicit-fallthrough` from libakerror's own `PROCESS`/`HANDLE`/`HANDLE_GROUP`, which fall through between `case` labels by design. Adopting it today would mean disabling both permanently to gain 5 -`-Wsign-compare`. The fallthrough half is filed upstream as -`deps/libakerror/TODO.md` item 8; revisit when that lands. +`-Wsign-compare`. The fallthrough half is filed upstream as `libakerror` issue #18; +revisit when that lands. **Vendored code is exempt, not fixed.** `deps/semver/semver.c` is listed directly in `add_library(akgl ...)`, so the target's `PRIVATE` options reach it; diff --git a/CMakeLists.txt b/CMakeLists.txt index fe85fff..8405d86 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -62,7 +62,7 @@ endif() # reads every argument or not, and 4 -Wimplicit-fallthrough from libakerror's # own PROCESS/HANDLE/HANDLE_GROUP, which fall through between case labels by # design. Adopting it would mean disabling both permanently to gain 5 -# -Wsign-compare. See deps/libakerror/TODO.md item 8. +# -Wsign-compare. See libakerror issue #18. if(AKGL_COVERAGE) if(NOT CMAKE_C_COMPILER_ID MATCHES "GNU|Clang") diff --git a/docs/20-tutorial-sidescroller.md b/docs/20-tutorial-sidescroller.md index bfefe92..688ab70 100644 --- a/docs/20-tutorial-sidescroller.md +++ b/docs/20-tutorial-sidescroller.md @@ -1064,8 +1064,7 @@ Add one line where you set up the player: The default facing logic clears every facing bit and sets one from the *movement* bits — so an actor that stops moving is left facing nowhere. Its state drops to bare `ALIVE`, which your character has no sprite for, and it stops being drawn. Clearing this field leaves the -facing bits wherever the control handlers put them. Making the default behave is tracked in -`TODO.md`. +facing bits wherever the control handlers put them. Making the default behave is issue #39. Run now. The arrow keys walk the player, the run animation plays, and the player stops at walls. diff --git a/docs/21-tutorial-jrpg.md b/docs/21-tutorial-jrpg.md index d75b0c4..f850e4f 100644 --- a/docs/21-tutorial-jrpg.md +++ b/docs/21-tutorial-jrpg.md @@ -997,10 +997,10 @@ Three things to get right, all of them cheap: - **Zero the struct first.** A binding is a struct copied into the map, so a stack local is fine — but an uninitialized field is a match against garbage. - **`handler_off` must be non-`NULL`.** `akgl_controller_handle_event` calls it without - checking. `jrpg_cmhf_ignore` is a handler that does nothing, which is what you want on the + checking, which is the other half of issue #81. `jrpg_cmhf_ignore` is a handler that does nothing, which is what you want on the release of a key whose press is the whole action. - **Set `button` to `SDL_GAMEPAD_BUTTON_INVALID`.** The keyboard and gamepad arms of the - match are evaluated together, and 0 is a real button. Recorded in `TODO.md`; until it is + match are evaluated together, and 0 is a real button. That is issue #81; until it is settled, name a button no gamepad reports. Run now. Standing near the elder and pressing Space opens their line; pressing it again diff --git a/plan.md b/plan.md index 3b2eedc..d9ee1a9 100644 --- a/plan.md +++ b/plan.md @@ -45,7 +45,7 @@ JRPG — with akbasic's harness ported so no sample in it can rot. | Tutorial assets | Vendor a curated Kenney.nl **CC0** subset, with `LICENSE`, a provenance manifest, and a refresh script | | Tutorial code | Real compiling, runnable targets under `examples/`, built by default and in CI | | Existing `README.md` | Split: the FAQ half seeds `docs/` (corrected); the developer-process half stays | -| Known defects | Documented inline in the owning chapter, cross-referenced to `TODO.md` | +| Known defects | Documented inline in the owning chapter, cross-referenced to the issue that tracks it | --- @@ -188,7 +188,7 @@ cannot anticipate: `include/akgl/error.h`. - **`akgl.pc` names no dependencies at all** — no `Requires:` — despite `akerror.h` being part of libakgl's public interface. Chapter 03 says so and gives the flags to add by - hand. (`TODO.md`.) + hand. (Issue #17.) --- @@ -352,7 +352,7 @@ a hazard. Exercises arcade physics, `physics.gravity.y`, `AKGL_ACTOR_STATE_MOVIN tilemap layers, and a custom `movementlogicfunc` (which is where `AKGL_ERR_LOGICINTERRUPT` stops being a table row and becomes something the reader writes). -This game forces the chapter to make three honest statements, all from `TODO.md`: +This game forces the chapter to make three honest statements, all from the defect record: - **`akgl_physics_arcade_collide` is not implemented** — it raises `AKERR_API`, and `akgl_physics_simulate` never calls `collide` at all. `arcade_move` does no clamping and @@ -433,7 +433,7 @@ covers. This plan does not fix it — replacing test fixtures is a separate change with its own blast radius, and it is not blocking the docs. It does two things: the tutorial assets get a clean -provenance story that does not depend on those files, and the finding goes into `TODO.md` +provenance story that does not depend on those files, and the finding goes into the tracker with file, functional consequence and blast radius, per the house practice of documenting defects against yourself. @@ -473,12 +473,12 @@ project exists to fix is documentation asserting things nobody checked: `norun` block is a decision that has to be justified. 4. **Do not restate signatures** — link the Doxygen reference, or `excerpt=` the header. 5. **Note the known defect where a reader would hit it**, with the guard to apply, linked - to `TODO.md`. + to its issue. Wave 2 is the integration pass, and the only genuinely serial step: build the TOC, insert cross-references between chapters and both tutorials, verify no chapter re-teaches upstream -material, reconcile terminology, cut the README's FAQ half, add the `TODO.md` entries, then -run the full gate. +material, reconcile terminology, cut the README's FAQ half, file the issues the writing turned +up, then run the full gate. ## Verification @@ -516,7 +516,7 @@ Specific things that must hold before this is done: ## Out of scope, deliberately -- Replacing the RPG-Maker-named test fixtures (recorded in `TODO.md` instead). +- Replacing the RPG-Maker-named test fixtures (issue #52 instead). - Fixing the false claims in `physics.h` and `registry.h`. The chapters document what the code *does*; correcting the header comments is a separate commit, since `AGENTS.md` requires style and behaviour changes to stay unbundled.