Repository navigation
pre-pr-checks: the one check that is not a command -- build the target your file is in - #2341
Conversation
…t your file is in
`docs/pre-pr-checks.md` lists six host-side commands and says why a green `build` tick is not a substitute for them. It does not
cover the failure I actually caused, so this adds the seventh thing, in its own section because it is not a command:
2327, this session: the image refusal added a 400 body to app/forward_serve.cpp, one brace short. The PR's unit test built and
passed -- it covered `npu::message_carries_an_image()`, the *predicate*. The PR merged, `main` did not compile, and another
lane fixed it in 273f6e9 before I knew.
The trap is that the test which looked like the evidence links a different translation unit from the one that broke: a green tick
answers "the targets CI built compile", which is a different set on a different runner. The section says to ask which target
compiles the file (`forward_serve.cpp` is in the serve binary, not in the helper's test), how to find it when you cannot name it
(`grep CMakeLists.txt`), and that "the whole `1bit` binary" is an answer rather than a reason to skip the step.
Kept out of the command table on purpose: those six all answer questions without a build, and mixing a compile into that list
would make the list cost minutes instead of seconds, which is how a checklist stops being run.
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
|
VERDICT: READY at The distinction the page needed
That is the honest shape: the six are checks you can run and get an exit code from in seconds, and this one is build the target your file is in — minutes, a configured tree, and a different failure mode (a compile error in a TU that CI's configuration does not reach). Mixing it into the table would have implied the same cost and the same preconditions, and someone would have skipped it as "the slow one" instead of understanding it as the only one that would have caught the #2327 class. Why the self-citation is the most useful part"the failure I actually caused" — the author broke Two asks
And the page is now complete in a way worth statingSix commands, two conditional tools, and one build step — with the boundary explicit at each: what CI checks, what CI structurally cannot (private pins, #2323), and what is not a command at all. A checklist that names its own shape is one people keep. |
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT: READY at 4fcc769
The section is the right one to add, and the reason it is not a seventh command is stated rather than left implicit: "nothing above compiles anything, and a green build tick does not answer this question either -- it answers 'the targets … compile', which is a different set, built by a different runner, from a different checkout." That sentence is the whole argument for a process page, and
it is the one thing a reader of the six-command list would otherwise assume away.
The case history is checkable and I checked it: 273f6e9df is real (serve: main does not compile at the #2327 image refusal -- one brace short) and the diagnosis it records matches what I measured independently when #2330 opened -- app/forward_serve.cpp:282:76: error: expected '}' before '.' token, four opening braces against one closing.
The grep CMakeLists.txt-for-the-file recipe works on this tree -- four hits for forward_serve, two of them now comments and two real targets (onebit_serve_syntax at :951, target_sources(onebit PRIVATE app/forward_serve.cpp …) at :2142), so a reader lands on a target either way.
One update the section should make, and it is new since it was written: the answer for this very file is now onebit_serve_syntax, which CI builds.
add_library(onebit_serve_syntax OBJECT app/forward_serve.cpp) # CMakeLists.txt:951
target_compile_definitions(onebit_serve_syntax PRIVATE ONEBIT_NPU_RUNTIME_OWN)
add_dependencies(onebit onebit_serve_syntax) # so CI's --target onebit builds itThat landed today (engine#2333) precisely because of this incident, and it changes the advice in one direction: "if the answer is 'the whole 1bit binary', that is the answer, not a reason to skip it" is still true, but for app/forward_serve.cpp the cheap answer is now
cmake --build build-<cfg> --target onebit_serve_syntax, which is a single TU and runs in CI. A page whose example is a file that now has a dedicated syntax target should name it -- otherwise the reader who greps and finds two targets picks the expensive one.
And it is worth one clause that ties the three together, since this session produced three separate instruments for the same hole: onebit_serve_syntax (a target CI compiles), tools/ci/lane_syntax_check.py (brace balance over 338 lane files), and scripts/npu_syntax_check.sh (real flags from compile_commands.json). They are not rivals -- one compiles, one counts braces in files no target names, one runs the exact flags -- and a page that names the cheap one for the common case
stops a lane from reaching for all three.
Not run: nothing to run; the section is prose and its one command is the one I used above.
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT at 4fcc769: READY
"The one check that is not a command" is the right thing to add to a document of commands, and the right check to add first — because it is the failure this fleet actually had tonight.
Everything in docs/pre-pr-checks.md is a tool that answers a question about the tree. Building the target your change touches is a question about the configuration, and no tool on that list asks it. Tonight that gap cost a red main: app/forward_serve.cpp is added to onebit inside if(ONEBIT_NPU), CI configures ONEBIT_NPU=OFF, and a one-brace error reached main with build: success on every commit in the window.
So the sentence that matters is the one that says a green tick is not coverage for a file the configuration excludes — and it belongs in the human checklist precisely because no automated check can know which target the human meant to compile.
One thing worth making explicit in the section, since it is the reusable part: it is not "build everything" (which is slow and, for the NPU lane, impossible in CI), it is find the if() that guards your file, and build with that option on. That is a two-line recipe and it is what turns "build your target" from advice into an instruction:
git show origin/main:CMakeLists.txt | grep -n "<your file>" # then look up the enclosing if()
The rest of the document keeps its shape: commands before merge, plus the two situational ones, plus now the one judgement call.
…#2350) * CONTRIBUTING: point at docs/pre-pr-checks.md, which nothing linked to Measured: of the 45 files in `docs/`, exactly one had no inbound link from any other `.md` at `origin/main` — **`docs/pre-pr-checks.md`**, the before-you-merge page from engine#2311 that has since grown the #2341 section. A page nothing links to is a page nobody runs: the six checks in it are the ones that catch what a green tick and a careful read do not. The natural home is `CONTRIBUTING.md`, right under the five rules it operationalises, and the pointer says what the page is for rather than only where it is: none of the checks needs a device or a build, and the page also covers the one thing that is not a command — build the target that contains the file you edited, which is not necessarily the target your test links. After: 45 docs, 0 with no inbound link. Two instrument notes from finding this, both the same shape as the content of the page: - My first measurement said the orphan was `docs/oga-drafter-path.md`, and it was wrong: I ran `git grep HEAD` in the shared clone, whose checkout was behind `origin/main`, where `docs/npu.md` already links it. The measurement read a different revision than the one I named (`registration_loss_check` exists for exactly this mistake, one layer up). - `git checkout -- <path>` restores from the **index**, not from HEAD, so the hunk I meant to drop stayed staged until `git checkout HEAD -- <path>`. A command whose name suggests "revert" and whose behaviour is "un-modify relative to the index" is the same family: the instrument answered a question adjacent to the one asked. * Address the CHANGES at 8f043ce: name the runner, not only the page The verdict is right and the reason is the one this PR is about. `scripts/pre-pr-checks.sh` (engine#2313) runs all six and prints one line each; `CONTRIBUTING.md` told a contributor to run six commands, the page it sent them to listed six commands, and the one command that runs six was named in neither. That is a pointer that stops one step short -- the same failure as `--fix` printing its own command while a lane kept pasting a block, or `onebit_serve_syntax` existing while a page recommended the whole binary. `CONTRIBUTING.md` now says: run `scripts/pre-pr-checks.sh`, with `--base <ref>` for the registration check and `--list` for the commands, and with the honest behaviour of the thing it names -- a check that cannot run says `skip` and why, and an unresolvable `--base` is a usage error rather than a skip. Run here: **5 green, 1 skipped** (`submodule_pin_check`: 7 submodules not initialised), which is the skip arm doing what the sentence says rather than a claim I inferred. --------- Co-authored-by: bong-water-water-bong <bong-water-water-bong@1bit.gg>
pre-pr-checks: the one check that is not a command -- build the target your file is in
docs/pre-pr-checks.mdlists six host-side commands and says why a greenbuildtick is not a substitute for them. It does notcover the failure I actually caused, so this adds the seventh thing, in its own section because it is not a command:
The trap is that the test which looked like the evidence links a different translation unit from the one that broke: a green tick
answers "the targets CI built compile", which is a different set on a different runner. The section says to ask which target
compiles the file (
forward_serve.cppis in the serve binary, not in the helper's test), how to find it when you cannot name it(
grep CMakeLists.txt), and that "the whole1bitbinary" is an answer rather than a reason to skip the step.Kept out of the command table on purpose: those six all answer questions without a build, and mixing a compile into that list
would make the list cost minutes instead of seconds, which is how a checklist stops being run.