Contributor docs: the quick test loop, the reference pin, open gaps (#1283)

A fresh-clone walk-through as a new contributor found four gaps in the docs:

- No quick test loop: `scripts/check.sh` has nothing to check on a clean clone, and `cargo test -p <crate>` was not mentioned. "The loop" now says both.
- The doc-link lint is a full `cargo doc` of the workspace; METHOD and the script's header now say so.
- What to cite while a benilla-re gap is still open: the client address, with the benilla-re issue or pull request linked.
- When `reference/PIN` moves: only with a change that needs a newer benilla-re row, to a commit on its main. Stated in CONTRIBUTING and `reference/README.md`.

Docs only.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Sam Sung
2026-10-15 14:07:29 +07:00
committed by GitHub
parent 994f9f9610
commit b7bc7a7e3f
4 changed files with 15 additions and 7 deletions
+9 -4
View File
@@ -64,8 +64,12 @@ or a finding.
- **Weigh it.** A row says how sure it is: `inferred` is a lead to check before you rest on it,
`verified` with proof `one` or `two` is one or two readings of the bytes.
- **When it has a gap or is wrong,** take that to benilla-re: an issue there with what you need to
know, or a pull request that adds the finding (its `CONTRIBUTING.md` says how a finding is
written and checked). Then cite the client address here, as the comments do.
know, or a pull request that adds the finding (its `docs/CONTRIBUTING.md` says how a finding is
written and checked). Then cite the client address here, as the comments do, and link that
issue or pull request in yours while it is open.
- **The vendored tables.** `reference/` holds the benilla-re tables benilla's tests read, at the
commit in `reference/PIN`; its README says how to move the pin. Move it only when your change
needs a row benilla-re has after the pin, to a commit on benilla-re's main.
## How a change is judged
@@ -145,8 +149,9 @@ out of scope is closed with the reason.
- A capture runs through `scripts/visual.sh`, whose recipe is the header of
`crates/benilla-app/src/capture/mod.rs`. Pixel questions go through `benilla-visual crop`,
`series` and `hotspot`.
- **The loop.** `cargo play` builds and runs the play profile. `scripts/check.sh` verifies a
round of work; `scripts/gates.sh` is the full chain, and it opens a window for the engine boot
- **The loop.** `cargo play` builds and runs the play profile. `cargo test -p <crate>` runs one
crate's tests, the quickest loop. `scripts/check.sh` verifies a round of work: the crates your
branch changed against main and their dependents, so on a clean clone it has nothing to check; `scripts/gates.sh` is the full chain, and it opens a window for the engine boot
checks, so it needs a display. `WOW_STOCK_UI=1` boots a dev build on the stock interface
alone, without benilla's layer. Work on a branch.
+1 -1
View File
@@ -75,7 +75,7 @@ crate of its own or a fork, and benilla opens a piece of itself to such a crate
## Gates
- **The land gates**: `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets
-- -D warnings`, `cargo test --workspace`, the doc-link and render-pass lints, the vendored-reference and message-catalog checks, the player
-- -D warnings`, `cargo test --workspace`, the doc-link lint (a full `cargo doc` of the workspace) and the render-pass lint, the vendored-reference and message-catalog checks, the player
build without the `dev` feature with its own tests, and the engine boot checks, as
`scripts/gates.sh`. It runs on the tree that lands, before it lands; it is memoized on the
tree. The tests that read the install or the addon corpus skip where the data is absent, and
+3 -1
View File
@@ -5,7 +5,9 @@ reads, under their benilla-re names, taken at the commit `PIN` holds (40 hex dig
documents every column (`tables/README.md`) and rebuilds each table from the client's exe; nothing
here is edited by hand, and nothing here is Blizzard content.
Update: put the new benilla-re commit in `PIN`, then
The pin moves when a change needs a row benilla-re has after it, and with that change: to a
commit on benilla-re's main (the script refuses any other), then the sync, then the tests that
read the table. Update: put the new benilla-re commit in `PIN`, then
```
scripts/sync-reference.py <benilla-re checkout> # copy the tables at the PIN
+2 -1
View File
@@ -1,7 +1,8 @@
#!/usr/bin/env python3
"""Fail on a doc link whose target is declared nowhere in the workspace.
It reads rustdoc's unresolved-link warnings and fails on a `crate::`, `super::`, `self::` or
It runs `cargo doc` over the whole workspace (a full doc build, minutes on a cold tree) and reads
rustdoc's unresolved-link warnings and fails on a `crate::`, `super::`, `self::` or
`Self::` path whose leaf name is declared nowhere: the item is gone. Every other warning is a
convention here, not rot (a private module named through its parent, another crate's module
named with `crate::`, a bare name for an unimported bevy type).