Files
Triforce-Source/docs/workflow.md
ruckus7382sfgsgdf 34b3683441 Triforce v0.2.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:32:48 -06:00

7.0 KiB

Workflow: from report to release

How work moves through Hookshot, and how to decide what to work on next. It is written for people and for AI agents alike (agents: AGENTS.md sends you here). CONTRIBUTING.md still holds the rules that never bend, above all that no game files or anything made from them leave your PC.

The goal of this page is the order of work: with dozens of contributors and agents working at once, the project moves fastest when everyone picks from the same priorities, claims before starting, and leaves a trail the next person can follow.

1. Where work comes from

Source What lands there
GitHub issues (game problem, build problem, idea) the record: version, hardware, place in the game, hookshot_log.txt
Tracking issues ([Tracking] ...) one per family of reports (AMD rendering, no mesh shaders, Linux, VRAM, missing walls, FPS, ...)
Discord #bug-reporting (forum) first reports, often without a log; turn the reproducible ones into issues
Discord #dev-work claims, progress, review requests
Discord #dev-stuff security scan results (Syntak): handled before anything else
CI a red check on main is everyone's first problem

2. Priority: what to work on first

Score a problem as severity x reach x confidence and work from the top. Write the three parts in the issue or the claim, so others can see why it was picked. The scored, sorted list of open work is docs/worklist.md: pick from its top, and add new problems there with their three parts.

Severity

Level Weight What it means
S0 8 Security issue; crash, hang, device lost or a PC freeze; lost or corrupted saves; the builder cannot build
S1 5 Cannot progress or cannot start: black screen, missing walls that block a dungeon, softlock, menus unusable
S2 3 Wrong but playable: visual corruption, missing objects, audio out of sync, a large frame-rate loss (over 20%)
S3 1 Polish: small visual issues, small frame-rate gains, settings, features

Reach: the systems people run

Reach is the share of players on the hardware the problem affects (1.0 when it affects everyone). Two numbers feed it, and both change, so read them again rather than trusting old ones:

  • Who reports problems: python -I scripts/hardware_report.py counts the GPU vendor, card class and OS in the issue forms (it needs the gh CLI). As of 2026-11-10, of 399 issues that named their hardware: AMD 51%, NVIDIA 35%, Intel 3.5%; by class RX 6000 16%, AMD APUs and handhelds 12%, RX 9000 10%, RTX 40 9%, RTX 50 8.5%, RTX 30 7%, cards without mesh shaders 14.5%; Windows 57%, Linux and SteamOS 17%. This over-counts hardware where things break.
  • Who plays: the Steam Hardware Survey is the best public picture of PC gaming hardware (vendor, card, OS). Use its current numbers for the installed base.

A problem that hits a large installed base, or that dominates the reports, ranks high either way.

Confidence

Weight
Reproduced by you, or by a maintainer, with a log 1.0
Two or more reporters with logs 0.7
One report, or no log 0.4 (ask for the log first)

Hardware tiers: stability across machines

A change must not break a higher tier to help a lower one.

Tier Hardware What it means
1 NVIDIA RTX 20-50 and AMD RX 6000-9000, on Windows; the same on Linux (NVIDIA driver, Mesa RADV); Steam Deck Must keep working: test here before merge, regressions are S0/S1
2 AMD APUs and handhelds (ROG Ally, Legion Go, 780M/890M/8060S), Intel Arc Fixed when reported, tested when someone with the hardware can
3 Cards without mesh shaders (GTX 10/16, RX 5000 and older) Best effort through the fallback; never at a Tier 1 cost

Today Tier 1 testing is mostly NVIDIA; AMD files half the reports. AMD stability is the largest gap, so an AMD Tier 1 problem with a log outranks an NVIDIA one of the same severity.

3. The lifecycle

  1. Triage. Reproduce if you can. Find the tracking issue it belongs to, or open the issue (with the log). Score it (section 2).
  2. Claim. Before starting, say so in Discord #dev-work and on the issue: what, why (the score), and on what hardware you can test. Search open PRs first: two people fixing the same thing is the most common waste here. Drop a claim out loud when you stop.
  3. Fix. A branch from current main, one topic. Find the cause before the fix: a log, a trace, a measurement.
  4. Test.
    • A game-free test that fails without the change (see AGENTS.md: tests read the source).
    • python -I -B tests/run_all.py, all of it.
    • In the game, on your hardware: what you did and what you saw, with numbers from hookshot_log.txt for performance.
    • Add a row to tested configurations for each run you measured.
    • Say what you could not test (another OS, another vendor, real input devices).
  5. Pull request. Open the description with why the PR is needed; then what changed, how it was tested, what was not tested, and screenshots when it shows on screen. Link the issue and the tracking issue. Post the link in #dev-work.
  6. Review. Answer every comment in the PR. Rebase onto main before asking for review again: a PR that does not merge cleanly waits.
  7. Merge and release. Release branches are merged back into main right after a release, so that main's builds carry the release's fixes and the right version string (git describe only sees tags on main's history).
  8. Verify. Ask the reporter to retest on the release, then close the issue, or keep it open on the tracking issue with what is left.

4. The security lane

Security comes first: a scan result in #dev-stuff is triaged before other work.

  • Check every finding against the code; post the finding and the verdict for each (real / false positive, and why).
  • Fix the real ones in a PR, marked as security in the title.
  • Record false positives in the scanner as not exploitable, with the reason, so the next scan shows only new ones.
  • Never paste secrets, tokens or the scanner's private links in public channels.

5. Keeping the board readable

Suggested labels (a maintainer creates them): priority:P0 to priority:P3 (from the score), hw:nvidia, hw:amd, hw:intel, hw:no-mesh-shaders, os:linux, os:steamdeck, needs-log, reproduced, claimed. With them, the next thing to work on is the top of is:open label:reproduced -label:claimed sort:priority.

For agents

  • Start here, then AGENTS.md, then CONTRIBUTING.md.
  • Pick from the top of docs/worklist.md; add a scored row there for a new problem you find.
  • Prefer problems you can reproduce on the hardware you run on.
  • Claim before working, report progress where you claimed, and post the PR there.
  • Measure, don't guess: every claim about speed or correctness carries the log line, the test or the screenshot.
  • Never open a PR whose tests you have not run, or that has not been rebased onto main.