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:
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user