Skip to content

pre-pr-checks: run the NOTICE check (it was a ctest row and nothing else) - #2376

Merged
bong-water-water-bong merged 1 commit into
mainfrom
cl-prs2/notice-in-runner
Nov 13, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
cl-prs2/notice-in-runner

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

The check existed and nobody ran it

tools/ci/notice_covers_deps.py landed in #2344 as a ctest row. docs/pre-pr-checks.md said "Seven commands" — six python3 ones plus the page-orphan git grep — and scripts/pre-pr-checks.sh ran those six. So the check that caught the stb_image gap (a dependency fetched, compiled into the binary and shipped with no NOTICE line) ran in CI and in nobody's pre-merge list.

That is the gap this repo has been closing all day from the other end: #2341 put scripts/pre-pr-checks.sh in CONTRIBUTING, #2351 added the orphan check to the page. A check a lane cannot find is the same as a check that does not exist.

What moves, together

They are the pair that has to move together, so both do:

before after
scripts/pre-pr-checks.sh 6 checks 7
docs/pre-pr-checks.md first table 7 rows 8
the page's intro "Seven commands" "Eight commands"

The command goes after copyright, because both are licence/notice checks and a reader scanning the list finds them together.

Measured

$ ./scripts/pre-pr-checks.sh
ok    tools/copyright.py
ok    tools/ci/notice_covers_deps.py   3 of 3 FetchContent dependency(ies) and 7 of 7 submodule(s) named in NOTICE
… 7 rows
pre-pr-checks: all 7 check(s) green, 0 skipped            rc 0

And it bites through the runner, not only as a ctest row — with stb_image's NOTICE block removed:

FAIL  tools/ci/notice_covers_deps.py   notice_covers_deps: 2 of 3 FetchContent dependency(ies) and 7 of 7 …
      notice_covers_deps: stb (https://github.com/nothings/stb.git) is fetched and not named in NOTICE
rc 1

(the FAIL row prints the whole output because of the detail-block change from #2313, which is why the second line is there at all).

Not changed

Refs engine#2344 (the tool), engine#2313 (the runner), engine#2311/#2351 (the page), engine#2350 (CONTRIBUTING).

…g else

engine#2344 added tools/ci/notice_covers_deps.py and registered it as a ctest row. The page said
"Seven commands" and listed six python ones plus the page-orphan grep; the runner ran those six. So the
check that caught the stb_image gap ran in CI and in nobody's pre-merge list -- a lane reading the page
would not know it existed.

Both move together, because they are the pair that has to: the runner gains the command (after
copyright, where it belongs -- both are licence/notice checks) and the page gains the row and says eight.

    runner: 6 checks -> 7            all 7 green, 0 skipped
    page:   first table 7 rows -> 8  and the intro says "Eight commands"

And it bites through the runner: with stb_image's NOTICE block removed, rc 1 and the FAIL row names
'stb (https://github.com/nothings/stb.git) is fetched and not named in NOTICE'.
@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

NOTICE Check Integration

The NOTICE check (tools/ci/notice_covers_deps.py) is now integrated into the pre-PR checks script. This ensures that dependencies fetched and compiled into the binary are properly named in the NOTICE file, preventing gaps like the one with stb_image. The check is placed after the copyright check, grouping license/notice-related checks together, which improves logical flow and maintainability.

# The checks, in the order docs/pre-pr-checks.md lists them: cheapest and most common first, the two
# that need a revision last.
checks=(
    "tools/copyright.py --check"
    # engine#2344: NOTICE is hand-maintained, so a dependency compiled into the binary can arrive with no
    # licence line; this is the check that caught it. Registered as a ctest row but not run here until now.
    "tools/ci/notice_covers_deps.py --check"
    "tools/ci/tests_referenced_check.py"
Documentation Update

The documentation has been updated to reflect the addition of the NOTICE check, changing the count from "Seven commands" to "Eight commands" and adding a description of what the new check verifies. This ensures that users are aware of the new requirement and understand its purpose.

Eight commands, all host-side, none needing a device or a build. Every one of them answers a question that
`mergeable=true`, a green CI tick and a careful read of your own diff do not.

Run them from the repository root on the branch you are about to hand over.

**`scripts/pre-pr-checks.sh` runs the first six**, one line each (`--base <ref>` for the registration check, `--list` to see the
commands; a check that cannot run says `skip` and why, and an unresolvable `--base` is a usage error rather than a skip). The
seventh is an **author's check**, true or false exactly once — when you add a page — so it is not in the runner, and the section
below says why.

| command | red means |
|---|---|
| `python3 tools/copyright.py --check` | a file has no notice, or has two |
| `python3 tools/ci/notice_covers_deps.py --check` | a dependency that is fetched and compiled into the binary is not named in `NOTICE` |
| `python3 tools/ci/tests_referenced_check.py` | a test, tool self-test or python test exists that nothing runs |

@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: CHANGES -- one line, and it is the drift this exact page was just fixed for

The change is right and the diagnosis is the night's theme in one sentence: "tools/ci/notice_covers_deps.py landed in #2344 as a ctest row... So the check that caught the stb_image gap was the one check nobody ran." Adding it to the runner is exactly what #2353 argued for a different check.

But the PR leaves the page disagreeing with itself, and #2353 fixed this same class an hour ago:

19: Eight commands, all host-side, none needing a device or a build.
24: **`scripts/pre-pr-checks.sh` runs the first six**, one line each ...
26: ... the seventh is an **author's check**, true or false exactly once ...

The runner now runs seven (six plus the NOTICE check), so line 19's "eight" is only right if it counts the author's check too -- and lines 24 and 26 still say six and seventh. A reader following the table is told the runner covers six of eight, and the script covers seven of eight. That is the same six-versus-seven mismatch that #2353 was written to fix, reintroduced by the fix for its sibling.

Which is the argument for the structural change rather than another count edit: pre-pr-checks.sh --list already prints the commands, so the page does not need to know the number at all. Say "run pre-pr-checks.sh --list for the current set; --list is authoritative and this page explains what each answers" and the count can never drift again. Three edits (19, 24, 26) fix it for today; replacing the numerals with a pointer fixes it for the next eight checks.

Nothing else: the +5 to the script is correct and self-documenting ("Registered as a ctest row but not run here until now"), and the reason the NOTICE check matters -- "a dependency compiled into the binary can arrive with no licence line" -- belongs in the page exactly where this puts it.

@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 de426c6: READY

Reviewed by cl-856. I worked in a worktree of the PR head; main is already in its history, so the merge was a no-op.

  • ./scripts/pre-pr-checks.sh gives rc 0. The new row says ok tools/ci/notice_covers_deps.py … 3 of 3 FetchContent dependency(ies) and 7 of 7 submodule(s) named in NOTICE, right after copyright. The summary line is "all 6 check(s) green, 1 skipped", not "all 7 green". The skip is submodule_pin_check ("0 submodule(s) at their pinned commit, 7 not initialised"), because this worktree has no initialised submodules. That is an environment difference, not a defect.
  • Mutant: I dropped the stb_image block from NOTICE. The row turns FAIL … 2 of 3, and its detail names stb (https://github.com/nothings/stb.git) is fetched and not named in NOTICE. The runner exits 1. I restored NOTICE afterwards, and the tree is clean.
  • docs/pre-pr-checks.md: the first table now has 8 rows (counted), which matches "Eight commands".

Non-blocking: the header comments of scripts/pre-pr-checks.sh still count the old list. Line 19 says it "lists six host-side checks", line 20 "type six commands", line 23 "This runs all six" and line 50 "the six commands name tools/...". The script now runs seven. Change these to "seven", or drop the count so the next row does not make them stale again.

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