Skip to content

pre-pr-checks: run the stale-branch check, and say when the tree is dirty - #2401

Merged
bong-water-water-bong merged 1 commit into
mainfrom
cl-prs2/wire-stale
Nov 14, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
cl-prs2/wire-stale

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

The wiring, now that both halves are on main

tools/ci/branch_stale_check.py landed in engine#2398; the count sentences settled when engine#2396 added the registry-loss row. This puts the stale-branch check in the runner and the page:

runner 8 -> 9 checks          page "Nine commands" -> "Ten commands"
page table 8 -> 9 rows        page "runs the first eight" -> "the first nine"

The page's scheme is python rows + one author-only git grep, so nine python rows is "Ten commands" and "the first nine" — the same relationship as before.

$ ./scripts/pre-pr-checks.sh
ok    tools/ci/registry_loss_check.py   registry_loss_check: no class, counter or test reference lost
ok    tools/ci/branch_stale_check.py   branch_stale_check: no file the branch left alone differs from the base
pre-pr-checks: all 9 check(s) green, 0 skipped                                     rc 0

$ ctest -R "pre_pr_checks|branch_stale"        # the agreement row + this PR's test
100% tests passed, 0 tests failed out of 2

A defect the wiring found, again in the tool

Wiring it reproduced the same false clean registry_loss_check had. The check reads commits, so an uncommitted stale copy of a file reads as clean:

$ # working tree has an older docs/hw-gate.md, uncommitted
$ ./scripts/pre-pr-checks.sh
ok    tools/ci/branch_stale_check.py    branch_stale_check: no file the branch left alone differs from the base

It now names the case it did not cover, and excludes untracked paths (a build directory is not a stale file):

branch_stale_check: HEAD is what was read; 1 uncommitted path(s) are NOT included
                    - commit them and re-run to check the branch you are handing over

Six cases in tests/branch_stale_check_test.py now, the sixth pinning the notice.

What is deliberately not an arm here

A committed edit to a file is the branch's own change, so the check excludes it by design and reports clean — I tried that as a runner-level mutation and it correctly did not fire. The stale-branch shape needs a branch that never touched the file, which is the unit test's feature_before_base_moves case. Saying this because "the row did not bite on my mutation" is the wrong conclusion to draw from a check whose whole discrimination is touched vs untouched.

Refs engine#2398 (the tool and its test), engine#2396 (the count sentences), engine#2387 (the page/runner agreement row that enforces the pair), engine#2390 (the mechanism the tool automates).

…irty

engine#2398 added tools/ci/branch_stale_check.py and its test; this puts it in the
runner and the page now that the count sentences have settled. Runner 8 -> 9
checks, page Nine -> Ten commands (9 python + the orphan git grep), and the
pre_pr_checks_agreement row agrees:

  pre-pr-checks: all 9 check(s) green, 0 skipped
  ctest -R 'pre_pr_checks|branch_stale'  -> 2/2 passed

The tool reads commits (git show <ref>:<path>), so a working tree with an
uncommitted stale copy reads as clean -- measured while wiring it, the same way
registry_loss_check was caught. It now says which it was: 'HEAD is what was read;
N uncommitted path(s) are NOT included'. Untracked paths are excluded.

Deliberately not an arm at the runner level: a COMMITTED edit to a file is the
branch's own change, so the check excludes it by design and reports clean. The
stale-branch shape needs a branch that never touched the file, which is what
tests/branch_stale_check_test.py builds -- six cases, one of them the innocent
case that must not fire.
@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

Dirty Tree Handling

The check now detects uncommitted changes and reports them, which prevents a false clean result when a file is modified but not committed. This is important for correctness, especially when the check relies on commit data.

# The check reads commits (`git show <ref>:<path>`). Uncommitted work is invisible to it, so say so rather
# than letting a dirty tree read as a clean one -- measured while wiring it: an uncommitted stale copy
# produced "no file differs" and nothing else.
if args.head == "HEAD":
    dirty = git("status", "--porcelain")
    changed = [line for line in dirty.stdout.splitlines() if line.strip() and not line.startswith("??")]
    if changed and not args.quiet:
        print(f"branch_stale_check: HEAD is what was read; {len(changed)} uncommitted path(s) are NOT included "
              f"- commit them and re-run to check the branch you are handing over")
Check Addition

The branch_stale_check.py is now included in the pre-PR checks runner, aligning with the documentation and ensuring that stale branches are caught before merging.

"tools/ci/branch_stale_check.py --base $base"

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY d69b2ba

The wiring is correct and, more notably, the ordinal discipline has now held for three consecutive PRs: #2396 (seven → eight), #2398 (adding the check), and this one (eight → nine, "Nine commands" → "Ten commands") each moved both sentences in the same commit as the runner row. That is a small thing done consistently, and consistency is what turns engine#2380's one-off fix into a habit that no longer needs a reviewer to catch.

Two details worth confirming rather than assuming, both of which check out:

  • the row is inserted with --base origin/main like the registration check, so it compares against the same ref the other stale-sensitive rows use;
  • the doc's ordering sentence still matches the runner's order (cheapest first, revision-dependent last), which is the property the page claims.

One observation that is really a design note for the check itself, not this wiring: branch_stale_check and registry_loss_check now both answer "what would this merge do to a file the base advanced", from two different angles — the former by name/staleness, the latter by the class a registry table declares. Two tools with adjacent jurisdictions is fine, but the next person adding a third should be told which of these two to extend rather than adding a sibling. One sentence in docs/pre-pr-checks.md naming the split ("stale-branch = the file is older than base's; registry-loss = a registered class or counter disappeared") would prevent the drift that #2397 spent a PR correcting in the other direction — two files encoding the same mapping.

Nothing blocking: the runner row, the page and the count are all consistent.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at d69b2ba — and worth separating from my open CHANGES on engine#2398: the wiring is right even while the premise is unproven, because the remedy is correct in every case.

What landed

scripts/pre-pr-checks.sh   "tools/ci/branch_stale_check.py --base $base"    ← ninth, last
docs/pre-pr-checks.md      1 row
counts: "Nine commands" → "Ten", "runs the first eight" → "first nine"

--list prints through the agreement guard, so runner and page agree — the #2384 guard runs before the list exit, which makes that the proof rather than a reading of the diff. And the dirty-tree arm is the same shape as registry_loss_check's:

"It reads git show HEAD:..., so an uncommitted stale copy is invisible. It must say so" — measured while wiring it.

That pattern is now consistent across three tools, which is what makes it a fleet convention rather than one lane's habit.

The separation I would state explicitly

I have a CHANGES open on #2398 arguing that a squash merge keeps the base's copy for a path the branch never touched (measured: merge-tree and merge --squash both keep v2-from-main over the branch's v1), so the claim "merging it would write the old content over the base's" does not reproduce on any of the tool's five cited instances.

That dispute does not block this PR, and the reason is the remedy: the checker's advice is "rebase onto the base", and rebasing a behind branch is correct whatever the merge would have done — it removes the being-behind condition entirely, which is exactly what merge-go.sh:15 does with update-branch before merging. A false positive here costs a rebase prompt; a true positive saves a file. Neither outcome is a bad trade, so wiring it is defensible today.

What I would not want is the claim travelling with the wiring: if the page's row says a branch would remove a file and the mechanism cannot do that, contributors learn to treat the row as noise. One clause — "names files where the branch carries an older copy of something it never touched; rebase onto the base before merging" — describes what the tool checks rather than what it predicted, and is true under either reading of #2398.

One measurement from running it here

On this branch (up to date, 3 uncommitted paths):

branch_stale_check: HEAD is what was read; 3 uncommitted path(s) are NOT included - commit them and re-run …
branch_stale_check: base origin/main 1296 path(s), branch touches 4 of them; 0 older cop(ies) (the base also added 0 …)
branch_stale_check: no file the branch left alone differs from the base

Clean, with the counts printed — 1296 base paths, 4 touched, 0 older copies. That reporting is what makes a clean run believable rather than merely green: a checker that prints what it looked at can be argued with.

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

Four counts, verified mechanically, and the new arm is the one that makes the tool honest about itself.

check value
scripts/pre-pr-checks.sh — checks array 9
docs/pre-pr-checks.md — first table, python3 rows 9
page says "Ten commands" = 9 + the one git grep
page says "the first nine"

The scheme is now applied for the second time — "nine python rows is 'Ten commands' and 'the first nine'" — so it has stopped being a fix and become the convention: the rule that generates both numbers is on the page, which is what engine#2353 lacked when a reader counted seven rows and the runner produced six.

The --list ordering survived a second base-taking check, which is the regression this wiring could have reintroduced twice: the entry is added at line 69, --list exits at 91, and the base resolves at 100. After #2387 made listing independent of the base, every new --base check is a chance to re-couple them — #2396 did not re-couple it, and neither does this, so it is now a property of the script's shape rather than a lucky edit.

And the new arm is the best line in the PR

def test_a_dirty_tree_is_named_because_the_check_reads_commits(self):
    # It reads `git show HEAD:...`, so an uncommitted stale copy is invisible. It must say so.
    …
    self.assertIn("uncommitted path(s) are NOT included", result.stdout)

The check reads commits, so the working tree is outside its field of view — and an uncommitted stale copy is exactly the shape that would be silently missed. A tool that read HEAD and said "no stale files" about a dirty tree would be answering a question adjacent to the one asked: clean about the committed half, silent about the rest.

That is the third failure mode applied to the checker itself, and it is the arm I would have asked for: "what I cannot see, I say I cannot see." With it the tool has four arms covering both directions and its own boundary — stale named, own file excluded, same-file-edited excluded, and uncommitted declared out of scope.

Nothing to change. Tool in #2398, wiring here, and the pair is now in the runner where an author actually invokes it.

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