docs(contributing): a PR's switch carries its recommended value from the first push; measurements gate leaving WIP #1634

Merged
HumanBean merged 1 commit from dyst/Longshot:docs/switch-default-wip into main 2026-11-18 19:00:49 +00:00
Member

Type: docs · Risk: low · Tested on: none (docs only) · Needs: none

TL;DR

A new switch for a change meant for players used to stay off in its pull request until the change was measured. But
the Test Farm, testers and the author's own runs test a branch as it is, so they were testing main's behaviour instead
of the change. This makes the rule: the switch carries the value the PR proposes to ship from its first push, and the
measurements decide when the PR leaves work in progress, not when the change turns on.

Breakdown

  • Who it helps: anyone testing a pull request (the Test Farm, testers, authors' A/B runs): they test what would merge.
  • What was wrong: CONTRIBUTING.md said a switch stays off when "not yet measured enough", so a WIP change was off in the very builds meant to test it.
  • What changes: a switch for a change meant for players is on by default in its branch from the first push; off by default is for switches only meant for testing.
  • What does not change: the measurements and the run on the author's PC are still needed to leave WIP; the switch is still how to turn a change off.
  • How it was checked: tests/test_doc_anchors.py passes (the new link to "Ready for review" resolves).
  • What is still open: nothing.
  • Risk: low: a docs change; a WIP change that turns out worse now has to be turned off or dropped before it leaves WIP, which the docs say.

Why

Testers and the Test Farm build a pull request as it is and don't set its switches. With the change off by default
"until measured", their runs said nothing about the change. The maintainers decided the default should be what the PR
proposes to ship, and the evidence should gate leaving WIP instead (the discussion behind #1617, the page bitmap, now
merged on by default).

What changed

The rule in its three places, worded to agree:

  • CONTRIBUTING.md, Code and data conventions: a switch ships at its recommended value; the PR carries it from its
    first push, WIP or not; the measurements take it out of WIP; if they go against it, turn the default off or drop the
    change before it leaves WIP, and say which.
  • docs/development.md, Switches for testing and debugging: the same in brief.
  • docs/agent-pull-requests.md, Open and update: the step for agents.

Measurements

Verdict: nothing to measure: a docs change.

Flags and settings

None.

Testing

Tested: python -I -B tests/test_doc_anchors.py passes on Windows. python -I -B tests/run_all.py on Windows: 576 passed, 69 failed, every failure also on main 35a4a9fc on this PC (test_prepare_cache_save fails there too; test_texture_tile_upload failed under load and passes alone). No game run: the change is docs only.

Not tested: nothing the game runs is changed.

Must be tested:

  • None.

Risks

What could break: nothing in the game; the rule asks more of a WIP author whose measurements go against the change (turn it off or drop it before leaving WIP).

Turning it off: revert the commit.

Compatibility: Nothing changes.

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).
  • 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.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** docs · **Risk:** low · **Tested on:** none (docs only) · **Needs:** none ## TL;DR A new switch for a change meant for players used to stay off in its pull request until the change was measured. But the Test Farm, testers and the author's own runs test a branch as it is, so they were testing main's behaviour instead of the change. This makes the rule: the switch carries the value the PR proposes to ship from its first push, and the measurements decide when the PR leaves work in progress, not when the change turns on. ## Breakdown - **Who it helps:** anyone testing a pull request (the Test Farm, testers, authors' A/B runs): they test what would merge. - **What was wrong:** CONTRIBUTING.md said a switch stays off when "not yet measured enough", so a WIP change was off in the very builds meant to test it. - **What changes:** a switch for a change meant for players is on by default in its branch from the first push; off by default is for switches only meant for testing. - **What does not change:** the measurements and the run on the author's PC are still needed to leave WIP; the switch is still how to turn a change off. - **How it was checked:** `tests/test_doc_anchors.py` passes (the new link to "Ready for review" resolves). - **What is still open:** nothing. - **Risk:** low: a docs change; a WIP change that turns out worse now has to be turned off or dropped before it leaves WIP, which the docs say. ## Why Testers and the Test Farm build a pull request as it is and don't set its switches. With the change off by default "until measured", their runs said nothing about the change. The maintainers decided the default should be what the PR proposes to ship, and the evidence should gate leaving WIP instead (the discussion behind #1617, the page bitmap, now merged on by default). ## What changed The rule in its three places, worded to agree: - `CONTRIBUTING.md`, *Code and data conventions*: a switch ships at its recommended value; the PR carries it from its first push, WIP or not; the measurements take it out of WIP; if they go against it, turn the default off or drop the change before it leaves WIP, and say which. - `docs/development.md`, *Switches for testing and debugging*: the same in brief. - `docs/agent-pull-requests.md`, *Open and update*: the step for agents. ## Measurements **Verdict:** nothing to measure: a docs change. ### Flags and settings None. ## Testing **Tested:** `python -I -B tests/test_doc_anchors.py` passes on Windows. `python -I -B tests/run_all.py` on Windows: 576 passed, 69 failed, every failure also on `main` 35a4a9fc on this PC (`test_prepare_cache_save` fails there too; `test_texture_tile_upload` failed under load and passes alone). No game run: the change is docs only. **Not tested:** nothing the game runs is changed. **Must be tested:** - None. ## Risks **What could break:** nothing in the game; the rule asks more of a WIP author whose measurements go against the change (turn it off or drop it before leaving WIP). **Turning it off:** revert the commit. **Compatibility:** Nothing changes. ## 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`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [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] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs(contributing): a PR's switch carries its recommended value from the first push; measurements gate leaving WIP
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 7s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 12s
2457eca92a
A change meant for players is on by default in its branch, WIP or not, so the Test Farm, testers and the author's own
runs test what would merge without setting anything; the switch stays the way to turn it off for an A/B or a
rollback. The measurements and the run on the author's PC decide when it leaves WIP, not when it turns on: if they go
against it, the default goes off or the change goes before it leaves WIP. Off by default is for a switch only meant
for testing. CONTRIBUTING.md (the rule), docs/development.md (its summary) and docs/agent-pull-requests.md (the step
for agents).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
HumanBean deleted branch docs/switch-default-wip 2026-11-18 19:00:49 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
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!1634
No description provided.