diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7e2e39..7c1b2a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -249,6 +249,39 @@ prove them. It is the one leg whose compiler is not the pinned one, for the reas `rust-toolchain.toml` gives, and it names its own toolchain and target and prints both on every run. +**`coverage`** measures line coverage with the compiler's own instrumentation and +judges it on the surface `.github/coverage/pinned-surface` names. That file is a +register of the kind `.github/invariants/rules` is - a kind, a path and the +reason on one line - and a line missing any of the three is refused, as is an +`area` naming nothing tracked and a tracked source file under an `area` that no +`module` line lists. The bar is on the modules the register names rather than on +the whole tree, and the number is in the script with the measurement it was set +from rather than here: a whole-repository percentage is met by covering the easy +half and missed by adding a large trivial module, so a bar over it cannot do what +#84 asks of one. The whole-tree figure is measured and printed on every run and +gates nothing, which is the half that is tracked rather than enforced. It reads +the counters with the tools in the pinned toolchain's sysroot rather than +whatever LLVM answers on the path, because a system LLVM of another version +answers differently and a verdict that depends on who ran it is not a verdict. +`.github/coverage/coverage.sh` holds the rules and the fixtures that prove them. + +**`mutation`** changes the code under the suite and reports which changes the +suite failed to notice, which is the question neither `test` nor `coverage` can +ask: a test that reaches a line and asserts nothing about the answer is green in +both. It runs weekly and on request rather than in front of a merge, because +every mutant is a build and a test run of its own, and IT GATES NOTHING. A +survivor obliges an issue on this board carrying the mutant in the analyser's own +words, the module it is in, and what would have caught it - not a re-run and not +a quiet acceptance, because a number produced on a schedule that nobody must +answer is a number nobody reads. There is deliberately no suppression register +beside it: excusing a mutant raises the published score with no test written, +which moves the number in the one direction that looks like progress and is not, +so a mutant nobody can kill is written into its issue with that reason and the +issue closed on it. Its scope is the `area` lines of the same register `coverage` +pins its bar to, so a source file added under one is mutated whether or not +anybody remembered it. `.github/mutation/mutation.sh` holds the rules and the +fixtures that prove them. + **`dependencies`** restores in locked mode, so a restore that would rewrite `Cargo.lock` fails rather than proceeding quietly, and scans the graph the committed lockfile declares against the advisory database. It reads back how many @@ -297,8 +330,13 @@ triples come from the `targets` leg's own reader through `.github/cross-toolchain/cross-toolchain.sh` holds the rules and the fixtures that prove them. -THREE RUNS REPORT AND REFUSE NOTHING, which is deliberate rather than an -oversight, AND THIS PARAGRAPH SAID TWO. **`External addresses in documents`** +FOUR RUNS REPORT AND REFUSE NOTHING, which is deliberate rather than an +oversight, AND THIS PARAGRAPH SAID TWO AND THEN THREE. Each move was a leg +arriving rather than a decision changing, and this one is `mutation` above, which +stood in the tree for twenty days before this section named it at all. The number +is a hand count over the entries in this section and no command derives it, so it +is right about what is described here and says nothing about what the tree +carries. **`External addresses in documents`** requests the addresses documents name and prints what answered; an address outside this repository that is down for an hour is not a defect here, and a gate that reddens for it teaches people that red means nothing. **`Scorecard