WIP: feat(dev): a starter pack: one setup check, the code graph, and the first steps in order #235

Draft

TrashPanda wants to merge 1 commit from TrashPanda/Longshot:feat/dev-starter into main

pull from: TrashPanda/Longshot:feat/dev-starter

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 0 Commits 1 Files changed 7 +501

TrashPanda commented 2026-11-13 16:28:38 +00:00

Contributor

• Copy link
• Copy Markdown

Why

A new developer finds the first steps spread over CONTRIBUTING.md, AGENTS.md, forge.md, test-requests.md and development.md, with nothing to say which are done on their PC. This puts them in order, adds one command that checks them, and sets up graphify, a local code graph that helps people and agents find their way in a large tree, so it can't take the game's files.

What changed

• setup: scripts/dev_setup.py (standard library, Windows and Linux) checks Python and requirements.txt's packages, the compiler, the Vulkan headers, the sign-in (forge.py whoami), the fork (forge-fork), the code graph and the game-free checks. It offers each missing step and does nothing without asking: --check reports only (exit 1 when a required step is missing), --yes does every step, --skip leaves steps out.
• graphify: installed with uv or pipx at a pinned version (graphifyy==0.9.101, PyPI, Apache-2.0); graphify update . builds graphify-out/graph.json from the source only (AST, no LLM, no network); graphify hook install keeps it current after commits, checkouts and merges.
  • .graphifyignore (new): everything .gitignore lists as the game's (work/, romfs/, *.nso, ...), build output and toolchains kept in a clone, third_party/ and the generated *_spv.h. dev_setup.py refuses to build the graph when it lacks one of the game's patterns.
  • .gitignore: graphify-out/.
  • hook install also writes a graph.json merge-driver line into the tracked .gitattributes; dev_setup.py puts the file back, since the graph is never committed.
• docs: docs/dev-starter.md (new), clone to first PR in order: the setup, the code graph and its rules, claiming work, dev_packs.py, the PR, and test requests (asking and helping). It links to the pages with the detail rather than repeating them. AGENTS.md (the reading list, Set up, a graphify step) and CONTRIBUTING.md (Development setup) point to it.
• tests: tests/test_dev_setup.py: .graphifyignore and dev_setup.py's NEVER_GRAPHED match .gitignore's game section; graphify-out/ is ignored; a short ignore file stops the graph step before it looks for or runs anything; --check and --yes ask nothing; an unknown --skip is refused.

Flags and settings

Flag	What it does	Default now	Recommendation	Helps on	Doesn't help on	Untested on
LONGSHOT_MINGW, LONGSHOT_VULKAN_HEADERS, RX_CPM	Existing build switches, unchanged: dev_setup.py only reads them to find the compiler and the headers	unchanged	-	-	-	-
dev_setup.py --check / --yes / --skip	A development script's options: report only, do every step, leave steps out	asks per step	asks per step: nothing is installed unasked	all	-	Windows

Measurements

main: 1ef93e79 (2026-11-13)
this PR: feat/dev-starter @ 938f2512

No speed numbers: a development script and docs, nothing in the game changes. The checks, and the setup on a fresh clone:

	main @ 1ef93e79	this PR @ 938f2512
python -I -B tests/run_all.py failures	3 (test_display_pointer, test_lift_cache, test_texture_staging_publication)	the same 3; test_dev_setup passes
dev_setup.py --yes, graphify step, fresh clone	-	graph built in 15 s (28,071 nodes), 4 hooks installed, git status clean
A stand-in work/lifted_secret.c and llvm-mingw/probe.c in the clone	-	neither in the graph

ok   headers   Vulkan headers under .../cpm
ok   signin    signed in to git.magicbean.dev as TrashPanda
ok   graphify  code graph at graphify-out/graph.json, kept current by git hooks
..   checks    504 passed, 3 failed, 18 skipped in 161 s (linux, 16 at once)

Testing

Tested: Linux (CachyOS, Python 3.14, AMD Ryzen 7 9800X3D). run_all.py: 505 passed, 3 failed, 18 skipped, the 3 also failing on main (test_texture_staging_publication is fixed by #215). dev_setup.py on a fresh clone: --check changed nothing; --yes built the graph, installed the hooks and left git status clean; a second --check showed graphify ok; the checks step read run_all.py's summary and named the failures. test_dev_setup.py fails when work/ is taken out of .graphifyignore. Each graphify example in the guide was run against the clone's graph.

Not tested: Windows (the llvm-mingw check, uv or pipx there, graphify hook install with Git for Windows), and a PC with nothing set up (the pip install and forge.py login offers ran only as far as their checks, since this PC has both).

Needs other testers:

• Windows: python -I scripts/dev_setup.py on a fresh clone, expecting each step reported, graphify installed and built, and git status clean afterwards (request to open)
• A new developer: follow docs/dev-starter.md from the clone, expecting no step missing or out of order (request to open)

Screenshots

Nothing on screen

Risk and rollback

Nothing in the game or the builds changes. The risk is a step that misreports (a compiler or headers not found) or a graphify release that changes its commands; the version is pinned. Reverting the commit is enough; graphify uninstall --purge removes graphify's hooks and its graph from a clone.

Reviewer notes

Where to look first: .graphifyignore against .gitignore's game section, and graphify_step in scripts/dev_setup.py (the refusal, and the .gitattributes put back). graphify is the user's choice, offered and never required. Its other commands (extract, label) can send text to an LLM; the guide says not to use them on this repository.

Issues

See #147

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. (Not applicable: no speed change; the checks on both sides are above.)
• 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.
• 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.
• Docs updated.

## Why A new developer finds the first steps spread over CONTRIBUTING.md, AGENTS.md, forge.md, test-requests.md and development.md, with nothing to say which are done on their PC. This puts them in order, adds one command that checks them, and sets up graphify, a local code graph that helps people and agents find their way in a large tree, so it can't take the game's files. ## What changed - setup: `scripts/dev_setup.py` (standard library, Windows and Linux) checks Python and `requirements.txt`'s packages, the compiler, the Vulkan headers, the sign-in (`forge.py whoami`), the fork (`forge-fork`), the code graph and the game-free checks. It offers each missing step and does nothing without asking: `--check` reports only (exit 1 when a required step is missing), `--yes` does every step, `--skip` leaves steps out. - graphify: installed with uv or pipx at a pinned version (`graphifyy==0.9.101`, PyPI, Apache-2.0); `graphify update .` builds `graphify-out/graph.json` from the source only (AST, no LLM, no network); `graphify hook install` keeps it current after commits, checkouts and merges. - `.graphifyignore` (new): everything `.gitignore` lists as the game's (`work/`, `romfs/`, `*.nso`, ...), build output and toolchains kept in a clone, `third_party/` and the generated `*_spv.h`. `dev_setup.py` refuses to build the graph when it lacks one of the game's patterns. - `.gitignore`: `graphify-out/`. - `hook install` also writes a `graph.json` merge-driver line into the tracked `.gitattributes`; `dev_setup.py` puts the file back, since the graph is never committed. - docs: `docs/dev-starter.md` (new), clone to first PR in order: the setup, the code graph and its rules, claiming work, `dev_packs.py`, the PR, and test requests (asking and helping). It links to the pages with the detail rather than repeating them. `AGENTS.md` (the reading list, Set up, a graphify step) and `CONTRIBUTING.md` (Development setup) point to it. - tests: `tests/test_dev_setup.py`: `.graphifyignore` and `dev_setup.py`'s `NEVER_GRAPHED` match `.gitignore`'s game section; `graphify-out/` is ignored; a short ignore file stops the graph step before it looks for or runs anything; `--check` and `--yes` ask nothing; an unknown `--skip` is refused. ## Flags and settings | Flag | What it does | Default now | Recommendation | Helps on | Doesn't help on | Untested on | |---|---|---|---|---|---|---| | `LONGSHOT_MINGW`, `LONGSHOT_VULKAN_HEADERS`, `RX_CPM` | Existing build switches, unchanged: `dev_setup.py` only reads them to find the compiler and the headers | unchanged | - | - | - | - | | `dev_setup.py --check` / `--yes` / `--skip` | A development script's options: report only, do every step, leave steps out | asks per step | asks per step: nothing is installed unasked | all | - | Windows | ## Measurements main: 1ef93e79 (2026-11-13) this PR: feat/dev-starter @ 938f2512 No speed numbers: a development script and docs, nothing in the game changes. The checks, and the setup on a fresh clone: | | main @ 1ef93e79 | this PR @ 938f2512 | |---|---|---| | `python -I -B tests/run_all.py` failures | 3 (`test_display_pointer`, `test_lift_cache`, `test_texture_staging_publication`) | the same 3; `test_dev_setup` passes | | `dev_setup.py --yes`, graphify step, fresh clone | - | graph built in 15 s (28,071 nodes), 4 hooks installed, `git status` clean | | A stand-in `work/lifted_secret.c` and `llvm-mingw/probe.c` in the clone | - | neither in the graph | ``` ok headers Vulkan headers under .../cpm ok signin signed in to git.magicbean.dev as TrashPanda ok graphify code graph at graphify-out/graph.json, kept current by git hooks .. checks 504 passed, 3 failed, 18 skipped in 161 s (linux, 16 at once) ``` ## Testing **Tested:** Linux (CachyOS, Python 3.14, AMD Ryzen 7 9800X3D). `run_all.py`: 505 passed, 3 failed, 18 skipped, the 3 also failing on `main` (`test_texture_staging_publication` is fixed by #215). `dev_setup.py` on a fresh clone: `--check` changed nothing; `--yes` built the graph, installed the hooks and left `git status` clean; a second `--check` showed graphify `ok`; the checks step read `run_all.py`'s summary and named the failures. `test_dev_setup.py` fails when `work/` is taken out of `.graphifyignore`. Each `graphify` example in the guide was run against the clone's graph. **Not tested:** Windows (the llvm-mingw check, uv or pipx there, `graphify hook install` with Git for Windows), and a PC with nothing set up (the pip install and `forge.py login` offers ran only as far as their checks, since this PC has both). **Needs other testers:** - Windows: `python -I scripts/dev_setup.py` on a fresh clone, expecting each step reported, graphify installed and built, and `git status` clean afterwards (request to open) - A new developer: follow `docs/dev-starter.md` from the clone, expecting no step missing or out of order (request to open) ## Screenshots Nothing on screen ## Risk and rollback Nothing in the game or the builds changes. The risk is a step that misreports (a compiler or headers not found) or a graphify release that changes its commands; the version is pinned. Reverting the commit is enough; `graphify uninstall --purge` removes graphify's hooks and its graph from a clone. ## Reviewer notes Where to look first: `.graphifyignore` against `.gitignore`'s game section, and `graphify_step` in `scripts/dev_setup.py` (the refusal, and the `.gitattributes` put back). graphify is the user's choice, offered and never required. Its other commands (`extract`, `label`) can send text to an LLM; the guide says not to use them on this repository. ## Issues See #147 ## Checklist ### For everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`). - [x] Rebased on current `main`. - [x] `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). - [x] Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. (Not applicable: no speed change; the checks on both sides are above.) - [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. - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated.

TrashPanda added 1 commit 2026-11-13 16:28:40 +00:00

feat(dev): a starter pack: one setup check, the code graph, and the first steps in order ... 938f2512ab

A new developer had the steps spread over CONTRIBUTING.md, AGENTS.md, forge.md, test-requests.md and
development.md, with nothing to say which were done on their PC.

- scripts/dev_setup.py: checks Python and the packages, the compiler, the Vulkan headers, the sign-in,
  the fork, the code graph and the game-free checks; offers each missing step and does nothing
  without asking (--check reports only, --yes does all, --skip leaves steps out).
- graphify (PyPI graphifyy 0.9.101, Apache-2.0), installed with uv or pipx: a graph of the code built
  locally from the source, no LLM, kept current by git hooks. .graphifyignore leaves out everything
  .gitignore lists as the game's, and dev_setup.py refuses to build the graph when it doesn't;
  graphify-out/ is ignored. hook install's graph.json merge driver line in .gitattributes is put
  back (the graph is never committed).
- docs/dev-starter.md: clone to first PR in order, linking to the pages with the detail: the setup,
  the code graph, claiming work, dev_packs.py, the PR, and test requests.
- AGENTS.md and CONTRIBUTING.md point to both.
- tests/test_dev_setup.py: .graphifyignore and dev_setup.py's list match .gitignore's game section,
  graphify-out/ is ignored, a short ignore file stops the graph before anything runs, --check asks
  nothing.

Assisted-by: Claude Opus 5.5

Some checks are pending

Hide checks

CI / Conventional Commit title (pull_request) Blocked by required conditions

Details

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions

Details

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions

Details

CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions

Details

Third-party parts / As their notes say (pull_request) Blocked by required conditions

Details

Third-party parts / The same as upstream (pull_request) Blocked by required conditions

Details

PR description / Description follows the template (pull_request_target) Successful in 29s

Details

This pull request is marked as a work in progress.

Some workflows are waiting to be reviewed.

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/dev-starter:TrashPanda-feat/dev-starter'

git switch 'TrashPanda-feat/dev-starter'

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Linux only

  

platform/steam-deck

Steam Deck

  

platform/windows

Windows only

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

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

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

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!235

No description provided.