diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 728ad3b91..1788110be 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -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 ` 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. diff --git a/docs/METHOD.md b/docs/METHOD.md index 836eb4369..3b60b9169 100644 --- a/docs/METHOD.md +++ b/docs/METHOD.md @@ -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 diff --git a/reference/README.md b/reference/README.md index 22e60d4cc..dd5475712 100644 --- a/reference/README.md +++ b/reference/README.md @@ -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 # copy the tables at the PIN diff --git a/scripts/doc-links.py b/scripts/doc-links.py index 0455fd65c..6e8c03e6f 100755 --- a/scripts/doc-links.py +++ b/scripts/doc-links.py @@ -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).