Skip to content

pre-pr-checks: the one check that is not a command -- build the target your file is in - #2341

Merged
bong-water-water-bong merged 1 commit into
mainfrom
pkg/prepr-build-target
Nov 13, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
pkg/prepr-build-target

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

pre-pr-checks: the one check that is not a command -- build the target 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 273f6e9df 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.

…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.
@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Documentation Clarity

The new section explains a critical build issue but could be more explicit about the specific scenario that leads to the problem. While it mentions that a test covering a predicate passed but the actual compilation failed, it does not clearly state how to detect such mismatches in the future. A clearer example or a checklist item for verifying translation unit linkage would improve the guidance.

## The one that is not a command: build the target that contains the file you edited

Nothing above compiles anything, and a green `build` tick does not answer this question either -- it answers "the targets CI built
compile", which is a different set, built by a different runner, from a different checkout.

    engine#2327, 2026-11-13: the image refusal added a 400 body to app/forward_serve.cpp and it was 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 273f6e9df ("serve: main does not compile at the #2327 image refusal") before I knew.

The trap is that the test which seemed to be the evidence links a different translation unit from the one that broke. Ask which
target compiles the file, not whether the file looks right:

    cmake --build build-<cfg> --target <that target> -j 6

`forward_serve.cpp` is in the serve binary, not in the helper's test. If you cannot name the target, `grep` `CMakeLists.txt` for
the file name -- and if the answer is "the whole `1bit` binary", that is the answer, not a reason to skip it.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at 4fcc769 — the seventh item is not a command, and putting it in its own section rather than in the table is the right call.

The distinction the page needed

"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" — with the citation 2327, this session: the image refusal add[ed]…

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 main tonight and is adding the check that would have prevented it. That is a stronger justification than any argument about practice, and it mirrors how the best items on this list arrived: #2332/#2333 came from the same break, registration_loss from a real lost update (#2288), doc_section_loss from #2183.

Two asks

  1. name the target per change, not in general — "build the target your file is in" is the instruction; the reader needs the mapping (app/forward_serve.cpp → the onebit target, or npu/… → onebit_npu_forward) or a one-liner that prints it (cmake --build … --target help | grep). Otherwise the seventh item is the only one on the page that cannot be executed from the page;
  2. state the cheapest sufficient form — -fsyntax-only on the single TU (tools: npu_syntax_check.sh -- compile-check the units CI never parses #2332's approach) versus a full target build (CMake: compile app/forward_serve.cpp outside the ONEBIT_NPU guard, so CI catches a one-brace break #2333's OBJECT library makes this automatic). If the page's instruction is "build the target", say that the minimum that catches a brace is a syntax check on the file, because the page's value is that each item is cheap enough to actually run.

And the page is now complete in a way worth stating

Six 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 bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 it

That 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 bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bong-water-water-bong
bong-water-water-bong merged commit 6888e93 into main Nov 13, 2026
9 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the pkg/prepr-build-target branch November 13, 2026 07:38
bong-water-water-bong added a commit that referenced this pull request Nov 13, 2026
…#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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant