feat(prs): one ready-for-review list: tested on your own PC, or what can't be run by hand said; two new Everyone boxes #1454

Merged
HumanBean merged 1 commit from HumanBean/Longshot:docs/ready-for-review into main 2026-11-17 20:03:33 +00:00
Owner

Type: feat · Risk: low · Tested on: Linux (the checker through forge.py pr status) · Needs: none

Why

What a pull request needs before it leaves WIP was spread over six places: the template's opening comment, CONTRIBUTING.md's step 4, docs/agent-pull-requests.md, docs/workflow.md, and Tooling's AGENTS.md and docs/forge.md. Each said it a little differently, and none said the author must have run the change on their own PC. PRs went to review with only a game-free check behind them, or with "not tested" and no reason. A fix whose own case can't be run by hand (hardware you don't have, a race you can't trigger) had no place to say so.

What changed

CONTRIBUTING.md has one list, Ready for review: out of WIP, and everything else points to it. Its central rule: you tested the change on your own PC (in the game, for a change the game runs). Other hardware is not needed to leave WIP; when the fix's own case can't be run by hand, Testing says so in a part of its own.

  • CONTRIBUTING.md: the new section's seven points:

    • done;
    • tested on your own PC, or Not testable by hand says what can't be run and why, and the change still runs once in the game;
    • the checks pass;
    • measured, every cost measured and in Risks;
    • the description complete and current;
    • the checklist true;
    • on current main.

    It also says what is not needed: runs on other hardware, a Test Farm result, an approval. Step 4 now links to the list instead of restating part of it.

  • .forgejo/pull_request_template.md:

    • the opening comment names the list;
    • Testing's Tested puts your own run first;
    • a new optional Not testable by hand: line, with a stand-in to fill in or delete;
    • two Everyone boxes: Tested on my own PC where it runs ... and Nothing gets worse that I know of: any cost ... is measured and in Risks.
  • scripts/check_pr_description.py: UNTESTABLE, Testing's optional part. It is read as a part of its own, so a Not testable by hand line written after Must be tested isn't taken for one of its items. Kept but empty, it is a problem.

  • docs/agent-pull-requests.md, docs/workflow.md: link to the list. An agent that only can't run the fix's own case runs the rest and says so in Not testable by hand.

  • tests/test_check_pr_description.py, tests/pr_description/good.md: the two new boxes in the sample; the template's unticked count 10 to 12; the new part filled in, after Must be tested, and empty.

Tooling's shared rules get the same list in short: MagicBeanDev/Tooling#20.

Measurements

Verdict: nothing to measure: rules, the template and the description checker, which the game doesn't run.

Flags and settings

None.

Testing

Tested: on this PC (Linux), forge.py pr status on this pull request from this branch's checkout, which loads this branch's scripts/check_pr_description.py (results in the first comment). The test file was read against the checker by hand, not run.

Not tested: python -I -B tests/run_all.py, including the updated tests/test_check_pr_description.py: not run on this PC (the person I work for runs no test suites here); CI's Python source checks run it on this PR.

Must be tested: None

Risks

What could break: every open pull request made from the old template lacks the two new Everyone boxes, so pr ready (and the PR description check) lists them as missing until its author adds and ticks them. That is the point, but it touches every open PR once. A description whose Testing has a line starting "Not testable by hand" is now read as that part.

Turning it off: revert the commit.

Compatibility: Nothing changes for players.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). Not run on this PC: waiting for CI's Python source checks.
  • 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.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Linux (the checker through `forge.py pr status`) · **Needs:** none ## Why What a pull request needs before it leaves WIP was spread over six places: the template's opening comment, CONTRIBUTING.md's step 4, docs/agent-pull-requests.md, docs/workflow.md, and Tooling's AGENTS.md and docs/forge.md. Each said it a little differently, and none said the author must have run the change on their own PC. PRs went to review with only a game-free check behind them, or with "not tested" and no reason. A fix whose own case can't be run by hand (hardware you don't have, a race you can't trigger) had no place to say so. ## What changed CONTRIBUTING.md has one list, *Ready for review: out of WIP*, and everything else points to it. Its central rule: you tested the change on your own PC (in the game, for a change the game runs). Other hardware is not needed to leave WIP; when the fix's own case can't be run by hand, Testing says so in a part of its own. - `CONTRIBUTING.md`: the new section's seven points: - done; - tested on your own PC, or *Not testable by hand* says what can't be run and why, and the change still runs once in the game; - the checks pass; - measured, every cost measured and in Risks; - the description complete and current; - the checklist true; - on current `main`. It also says what is not needed: runs on other hardware, a Test Farm result, an approval. Step 4 now links to the list instead of restating part of it. - `.forgejo/pull_request_template.md`: - the opening comment names the list; - Testing's *Tested* puts your own run first; - a new optional **Not testable by hand:** line, with a stand-in to fill in or delete; - two Everyone boxes: *Tested on my own PC where it runs ...* and *Nothing gets worse that I know of: any cost ... is measured and in Risks*. - `scripts/check_pr_description.py`: `UNTESTABLE`, Testing's optional part. It is read as a part of its own, so a *Not testable by hand* line written after *Must be tested* isn't taken for one of its items. Kept but empty, it is a problem. - `docs/agent-pull-requests.md`, `docs/workflow.md`: link to the list. An agent that only can't run the fix's own case runs the rest and says so in *Not testable by hand*. - `tests/test_check_pr_description.py`, `tests/pr_description/good.md`: the two new boxes in the sample; the template's unticked count 10 to 12; the new part filled in, after *Must be tested*, and empty. Tooling's shared rules get the same list in short: https://git.magicbean.dev/MagicBeanDev/Tooling/pulls/20. ## Measurements **Verdict:** nothing to measure: rules, the template and the description checker, which the game doesn't run. ### Flags and settings None. ## Testing **Tested:** on this PC (Linux), `forge.py pr status` on this pull request from this branch's checkout, which loads this branch's `scripts/check_pr_description.py` (results in the first comment). The test file was read against the checker by hand, not run. **Not tested:** `python -I -B tests/run_all.py`, including the updated `tests/test_check_pr_description.py`: not run on this PC (the person I work for runs no test suites here); CI's Python source checks run it on this PR. **Must be tested:** None ## Risks **What could break:** every open pull request made from the old template lacks the two new Everyone boxes, so `pr ready` (and the PR description check) lists them as missing until its author adds and ticks them. That is the point, but it touches every open PR once. A description whose Testing has a line starting "Not testable by hand" is now read as that part. **Turning it off:** revert the commit. **Compatibility:** Nothing changes for players. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). Not run on this PC: waiting for CI's Python source checks. - [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. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs(prs): one ready-for-review list: tested on your own PC, or what can't be run by hand said; two new Everyone boxes
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 23s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 34s
PR description / Description follows the template (pull_request_target) Failing after 3s
2d2bcd8ec2
CONTRIBUTING.md's Ready for review: out of WIP is the one list a PR meets to
leave WIP; the template, docs/agent-pull-requests.md and docs/workflow.md
point to it. Testing gains an optional Not testable by hand part, which the
checker reads as a part of its own (never a Must be tested item) and wants
filled in when kept. The Everyone list gains: tested on my own PC, and
nothing gets worse that I know of.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Collaborator

Possibly related, for context:

  • PR #891 WIP: docs(agents): a review checklist, and the review skill moves to Tooling — Overlapping contributor guidance and review checklist docs
Possibly related, for context: - PR #891 WIP: docs(agents): a review checklist, and the review skill moves to Tooling — Overlapping contributor guidance and review checklist docs
Author
Owner

Run on this PC (Linux), from this branch's checkout: forge.py pr status 1454 loads this branch's checker and counts 12 Everyone boxes, flagging only the run_all box left open. scripts/check_pr_description.py --file on this description with that box ticked and a filled Not testable by hand: line after Must be tested: complete, exit 0 (the line is not read as a Must be tested item). The same with the line empty: exit 1, "## Testing's 'Not testable by hand:' is empty: say what can't be run by hand and why, or delete it". tests/run_all.py not run here: waiting for CI.

Run on this PC (Linux), from this branch's checkout: `forge.py pr status 1454` loads this branch's checker and counts 12 Everyone boxes, flagging only the run_all box left open. `scripts/check_pr_description.py --file` on this description with that box ticked and a filled **Not testable by hand:** line after Must be tested: complete, exit 0 (the line is not read as a Must be tested item). The same with the line empty: exit 1, "## Testing's 'Not testable by hand:' is empty: say what can't be run by hand and why, or delete it". tests/run_all.py not run here: waiting for CI.
Author
Owner

Marked ready and force-merged at the request of the person I work for, before a pass that brings the open PRs to this standard. tests/run_all.py has not run on this change: CI skipped its Python source checks, and it isn't run on this PC. The Guide screenshots check fails on main itself since #1362, not from this PR.

Marked ready and force-merged at the request of the person I work for, before a pass that brings the open PRs to this standard. tests/run_all.py has not run on this change: CI skipped its Python source checks, and it isn't run on this PC. The Guide screenshots check fails on main itself since #1362, not from this PR.
HumanBean changed title from WIP: feat(prs): one ready-for-review list: tested on your own PC, or what can't be run by hand said; two new Everyone boxes to feat(prs): one ready-for-review list: tested on your own PC, or what can't be run by hand said; two new Everyone boxes 2026-11-17 20:03:06 +00:00
HumanBean force-pushed docs/ready-for-review from 2d2bcd8ec2
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 23s
CI / Workflow lint (actionlint) (pull_request) Successful in 24s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 34s
PR description / Description follows the template (pull_request_target) Failing after 3s
to 950e042cc2
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 5s
PR description / Description follows the template (pull_request_target) Failing after 7s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 9s
CI / Workflow lint (actionlint) (pull_request) Successful in 10s
Third-party parts / As their notes say (pull_request) Successful in 18s
2026-11-17 20:03:25 +00:00
Compare
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
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!1454
No description provided.