MagicBeanDev/Longshot

Watch

Fork

You've already forked Longshot

Code Issues 25 Pull requests 51 Projects 1 Releases Packages Wiki Activity Actions 86

WIP: test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve #25

Draft

dyst wants to merge 1 commit from dyst/Longshot:feat/doc-anchors into main

pull from: dyst/Longshot:feat/doc-anchors

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 3 Commits 1 Files changed 5 +116

dyst commented

2026-11-12 23:38:30 +00:00

First-time contributor

Why

The functions that keep design.md's hard-won rules (cross-queue waits, captures instead of live guest memory, passes split for clears and hazards) don't say so where they are defined, so an agent reading one sees a wait or a capture that looks redundant and may "simplify" it away. This puts a one-line pointer to the written rule above each, and a check that the pointers stay valid.

What changed

renderer: // doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here anchors above the functions behind docs/design.md §4's rules. Comments only; no code changes:
- rule 1: submit_job in gpu/vk/vk_replay.cpp (cross-queue event waits);
- rule 2: the pool captures in gpu/vk/vk_memory.cpp (the RX_VK_CAPTURE_POOL_MB comment above them: nothing the replay reads comes from live guest memory);
- rule 3: register_texture_queued in gpu/vk/vk_replay.cpp (registrations in order with the submits);
- rule 4: NOP_REPORT_COUNTER's timestamp scaling in replay(), gpu/vk/vk_replay.cpp (GPU timestamps drive dynamic resolution);
- rule 5: clear_after_draws and draw_hazards in gpu/vk/vk_draw.cpp (a clear after draws, and a draw that samples what its pass wrote, get a pass of their own).
build: rss_mb in nx2/build.py points to docs/compiler-memory-accounting.md.
tests: new tests/test_doc_anchors.py (standard library):
- every doc: anchor in our code (host/, gpu/, nx2/, scripts/, builder/; not eden, sirit or third_party) names a file under docs/ and, after #, one of its headings, by GitHub's anchor rule (slug(), anchors_of(): a repeated heading gets -1);
- those seven functions keep theirs, just above them (REQUIRED).
A renamed heading or a deleted anchor fails with the file and line.

Flags and settings

None

Measurements

Nothing to measure in the game: the change is comments and a check; no code changes.

What was run, on the GitHub version (NotRexed/Hookshot#2942), not on Longshot:

The new check passes. It fails as it should on an anchor to a heading that is not there (#4-lessons), and on the anchor above rss_mb deleted. It also checks the anchor rule itself (punctuation, code marks, underscores).
Every check that reads the changed files (207), through run_all.py with the Builder's tools, Windows: 201 pass. The 6 that fail (nx2/test_dll.py, test_driver_cache_folder, test_fpx_sticky, test_linux_driver_fault_guard, test_linux_update, test_readback_wait_bounded) fail the same way on main on that PC.

Testing

Tested: the runs under Measurements (on the GitHub version) and the game-free checks this description names.

Not tested: in the game (comments only, nothing runs differently); the checks ran on Windows only.

Needs other testers: None

Screenshots

Nothing on screen.

Risk and rollback

Nothing runs differently: the source changes are comments. The new check can fail a later PR that renames a heading in docs/design.md or docs/compiler-memory-accounting.md, or reshapes one of the seven functions so its marker moves; the message names the file and line. Reverting the commit is enough.

Reviewer notes

Carried over from NotRexed/Hookshot#2942 with the move to Longshot: the same change on Longshot's main, with its rename applied. Its review and discussion are there.

The dev-loop proposal's F2 (NotRexed/Hookshot#2636). Other functions can take anchors in later PRs, as their docs are written; the check covers every new one.

The checks were run on the GitHub version; this branch is the same change with the rename applied (the same files and line counts). Forgejo runs no checks, and they were not run again here. Only the checks that read the changed files were run, not the whole run_all.py.

Issues

See NotRexed/Hookshot#2636 (F2).

Checklist

For everyone

One topic.
The title is a Conventional Commit (type(scope): description).
Rebased on current main.
python -I -B tests/run_all.py run and passing (any failure that also fails on main is named above).
Tested in the game, or what wasn't is named under Testing.
Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests).
Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
No game files, dumps, build output or generated files.
third_party/ untouched (a new folder with a PROVENANCE.md instead).
The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

If applicable

AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
Flags table filled in; README / docs/development.md switch reference updated.
Screenshots for a change that shows on screen.
A row in docs/tested-configurations.md for each measured run.
MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed).
The SPIR-V headers regenerated with glslang (a shader changed).
A game-free test added for the fix, failing on main and passing here.
A check under tests/ that reads changed source updated in this PR, not weakened.
Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths.
Docs updated.

🤖 Generated with Claude Code

## Why The functions that keep design.md's hard-won rules (cross-queue waits, captures instead of live guest memory, passes split for clears and hazards) don't say so where they are defined, so an agent reading one sees a wait or a capture that looks redundant and may "simplify" it away. This puts a one-line pointer to the written rule above each, and a check that the pointers stay valid. ## What changed - renderer: `// doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here` anchors above the functions behind `docs/design.md` §4's rules. Comments only; no code changes: - rule 1: `submit_job` in `gpu/vk/vk_replay.cpp` (cross-queue event waits); - rule 2: the pool captures in `gpu/vk/vk_memory.cpp` (the `RX_VK_CAPTURE_POOL_MB` comment above them: nothing the replay reads comes from live guest memory); - rule 3: `register_texture_queued` in `gpu/vk/vk_replay.cpp` (registrations in order with the submits); - rule 4: `NOP_REPORT_COUNTER`'s timestamp scaling in `replay()`, `gpu/vk/vk_replay.cpp` (GPU timestamps drive dynamic resolution); - rule 5: `clear_after_draws` and `draw_hazards` in `gpu/vk/vk_draw.cpp` (a clear after draws, and a draw that samples what its pass wrote, get a pass of their own). - build: `rss_mb` in `nx2/build.py` points to `docs/compiler-memory-accounting.md`. - tests: new `tests/test_doc_anchors.py` (standard library): - every `doc:` anchor in our code (`host/`, `gpu/`, `nx2/`, `scripts/`, `builder/`; not eden, sirit or third_party) names a file under `docs/` and, after `#`, one of its headings, by GitHub's anchor rule (`slug()`, `anchors_of()`: a repeated heading gets `-1`); - those seven functions keep theirs, just above them (`REQUIRED`). A renamed heading or a deleted anchor fails with the file and line. ## Flags and settings None ## Measurements Nothing to measure in the game: the change is comments and a check; no code changes. What was run, on the GitHub version (NotRexed/Hookshot#2942), not on Longshot: - The new check passes. It fails as it should on an anchor to a heading that is not there (`#4-lessons`), and on the anchor above `rss_mb` deleted. It also checks the anchor rule itself (punctuation, code marks, underscores). - Every check that reads the changed files (207), through `run_all.py` with the Builder's tools, Windows: 201 pass. The 6 that fail (`nx2/test_dll.py`, `test_driver_cache_folder`, `test_fpx_sticky`, `test_linux_driver_fault_guard`, `test_linux_update`, `test_readback_wait_bounded`) fail the same way on `main` on that PC. ## Testing **Tested:** the runs under Measurements (on the GitHub version) and the game-free checks this description names. **Not tested:** in the game (comments only, nothing runs differently); the checks ran on Windows only. **Needs other testers:** None ## Screenshots Nothing on screen. ## Risk and rollback Nothing runs differently: the source changes are comments. The new check can fail a later PR that renames a heading in `docs/design.md` or `docs/compiler-memory-accounting.md`, or reshapes one of the seven functions so its marker moves; the message names the file and line. Reverting the commit is enough. ## Reviewer notes Carried over from [NotRexed/Hookshot#2942](https://github.com/NotRexed/Hookshot/pull/2942) with the move to Longshot: the same change on Longshot's `main`, with its rename applied. Its review and discussion are there. The dev-loop proposal's F2 ([NotRexed/Hookshot#2636](https://github.com/NotRexed/Hookshot/pull/2636)). Other functions can take anchors in later PRs, as their docs are written; the check covers every new one. The checks were run on the GitHub version; this branch is the same change with the rename applied (the same files and line counts). Forgejo runs no checks, and they were not run again here. Only the checks that read the changed files were run, not the whole `run_all.py`. ## Issues See [NotRexed/Hookshot#2636](https://github.com/NotRexed/Hookshot/pull/2636) (F2). ## Checklist ### For everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`). - [ ] Rebased on current `main`. - [ ] `python -I -B tests/run_all.py` run and passing (any failure that also fails on `main` is named above). - [x] Tested in the game, or what wasn't is named under Testing. - [x] Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests). - [ ] Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### If applicable - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [ ] Flags table filled in; README / docs/development.md switch reference updated. - [ ] Screenshots for a change that shows on screen. - [ ] A row in `docs/tested-configurations.md` for each measured run. - [ ] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). - [ ] The SPIR-V headers regenerated with glslang (a shader changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [ ] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. - [ ] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dyst added 1 commit

2026-11-12 23:38:30 +00:00

test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve 84be88a6d3

An agent reading submit_job, the pool captures or the pass splits does not see the rule they keep, and may
"simplify" a wait or a capture away. A comment above each (// doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here,
rule N) names where it is written; build.py's rss_mb names compiler-memory-accounting.md. tests/test_doc_anchors.py
checks that every doc: anchor in our code names a file under docs/ and one of its headings, and that these seven
functions keep theirs. The dev-loop proposal's F2 (#2636).

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

dyst changed title from ~~test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve~~ to WIP: test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve

2026-11-13 01:13:47 +00:00

dyst commented

2026-11-13 01:13:47 +00:00

Author

First-time contributor

Back to WIP under #48's process: this was carried over before the new template. Its description will be brought to the template and measured on Longshot (main against this PR, at named commits) when it's wanted for review; ask here if you'd like it sooner.

dyst commented

2026-11-13 01:58:15 +00:00

Author

First-time contributor

Description brought to Longshot's PR template (#48). Still WIP: its numbers are from the GitHub version, and it isn't rebased on current main; it gets measured on Longshot (main against this PR, at named commits) before it is marked ready.

dyst commented

2026-11-13 02:00:30 +00:00

Author

First-time contributor

Description moved to the template's Testing section and whole checklist (#72): what was tested, what wasn't, and what needs other testers (their test requests to open while this is WIP).

This pull request is marked as a work in progress.

This branch is out-of-date with the base branch

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u 'feat/doc-anchors:dyst-feat/doc-anchors'

git switch 'dyst-feat/doc-anchors'

Reviewers

No reviewers

Labels

Clear labels

accessibility

Barrier affecting people with disabilities

autorelease: pending

autorelease: tagged

bug

Something isn't working

dependencies

Pull requests that update a dependency file

documentation

Improvements or additions to documentation

duplicate

This issue or pull request already exists

enhancement

New feature or request

github_actions

Pull requests that update GitHub Actions code

good first issue

Good for newcomers

help wanted

Extra attention is needed

invalid

This doesn't seem right

needs measurements

Waiting for before/after measurements

question

Further information is requested

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

wontfix

This will not be worked on

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

MagicBeanDev/Longshot!25

Reference in a new issue

Repository

MagicBeanDev/Longshot

Title

Body

No description provided.

Delete branch "dyst/Longshot:feat/doc-anchors"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns