Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/pre-pr-checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ below says why. The table's order is the runner's order: cheapest and most commo
| `python3 tools/ci/submodule_pin_check.py --check` | a submodule's checkout is not the commit the tree pins |
| `python3 tools/ci/registration_loss_check.py --check --base origin/main` | your branch would drop rows `main` has |
| `python3 tools/ci/registry_loss_check.py --base origin/main` | a reviewed class, a `coverage` counter or a test's mention of a class that the base has is gone at the merge, not only at the endpoint (engine#2385, #2391) |
| `python3 tools/ci/branch_stale_check.py --base origin/main` | the branch carries an older copy of a file it never touched, so a squash merge would write that copy over the base's (engine#2398) |
| `python3 tools/ci/branch_stale_check.py --base origin/main` | the merge with the base conflicts, or would not keep a base change the branch never touched; a branch that is only behind gets a note (the merge keeps the base's copy, but the branch's tests ran on the older one) (engine#2398, #2410) |
| `git grep -l -F "$(basename <your new page>)" -- '*.md'` | nothing links to the page you just added — measured tonight: 45 docs, one with no inbound link, and it was the page whose whole subject is pre-merge checks |

Two more, for the moments they are for:
Expand Down
35 changes: 29 additions & 6 deletions tests/branch_stale_check_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@
# limitations under the License.
"""branch_stale_check_test.py -- the stale-branch shape, built in throwaway repositories.

Each case is the thing the check exists for: a file the base advances after the branch was cut, which the branch
never touched. The check must name it, must stay quiet when the branch does touch the file, and must refuse rather
than pass when a ref cannot be read.
A file the base advances after the branch was cut, which the branch never touched. The merge keeps the base's copy
(engine#2410), so the check names it as behind without failing; it fails on a conflict, stays quiet when the
branch does touch the file, and refuses rather than passes when a ref cannot be read.
"""

import os
Expand Down Expand Up @@ -64,11 +64,34 @@ def run_check(self, base, head):
return subprocess.run((sys.executable, CHECK, "--base", base, "--head", head), cwd=self.repo,
capture_output=True, text=True)

def test_a_file_the_base_advanced_is_named(self):
def test_a_file_the_base_advanced_is_named_as_behind_not_failed(self):
result = self.run_check(self.main, self.feature_before_base_moves)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
self.assertIn("note branch_stale_check: shared.txt - behind the base (the merge keeps the base's copy)",
result.stdout)
self.assertNotIn("FAIL", result.stdout)
self.assertIn("rebase before trusting them", result.stdout)

def test_a_squash_merge_keeps_the_base_copy_of_a_path_the_branch_never_changed(self):
# engine#2410: the premise the check rests on, measured rather than asserted.
git(self.repo, "checkout", "-q", "main")
merged = git(self.repo, "merge", "--squash", "feature")
self.assertEqual(merged.returncode, 0, merged.stdout + merged.stderr)
with open(os.path.join(self.repo, "shared.txt"), encoding="utf-8") as handle:
self.assertEqual(handle.read(), "v2 - merged while the branch was open\n")

def test_a_conflict_with_the_base_fails(self):
git(self.repo, "checkout", "-q", "feature")
self.write("other.txt", "the branch's other\n")
commit(self.repo, "the branch edits other.txt")
head = git(self.repo, "rev-parse", "HEAD").stdout.strip()
git(self.repo, "checkout", "-q", "main")
self.write("other.txt", "the base's other\n")
commit(self.repo, "the base edits other.txt too")
base = git(self.repo, "rev-parse", "HEAD").stdout.strip()
result = self.run_check(base, head)
self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
self.assertIn("shared.txt - the branch carries an older copy and never changed it", result.stdout)
self.assertIn("rebase onto the base", result.stderr)
self.assertIn("FAIL branch_stale_check: other.txt - the merge with the base conflicts here", result.stdout)

def test_the_branchs_own_file_is_not_reported(self):
# `feature.txt` does not exist on the base at all: the branch adds it and that must never be a failure.
Expand Down
77 changes: 48 additions & 29 deletions tools/ci/branch_stale_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,25 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""branch_stale_check.py -- a branch that is behind carries older copies of files it never touched.
"""branch_stale_check.py -- a branch that is behind, and what its merge would actually write.

The fleet squash-merges, so the branch's tree becomes main's tree for every path in the diff. On a branch cut
before another PR landed, the endpoint diff lists that PR's files as *modified* -- the branch's copy is the older
one -- and the squash reverts them. Five PRs on 2026-11-13/14 had exactly that shape: #358 would have removed
llama.cpp#357's alignment refusal and its case, #361 would have removed #355, #2021 would have removed #2387's
ctest row, #2387 would have removed #2366's arms, #2397 would have removed #2021's single-offset guard.
A branch cut before another PR landed carries the older copy of every file that PR changed. Its endpoint diff
(`git diff base..branch`, two dots) shows those files as reverted, and that reading is wrong: a squash merge applies
`merge-base..branch`, a path the branch never changed has no hunk there, and the base's copy survives (engine#2410,
measured in a scratch repo and on #2021 x cmake/tests-pre-pr-checks.cmake; the fleet merges with
`gh pr merge --squash`).

`git diff base...branch` (three dots) answers "what did the branch change", which is why it does not show this: the
files it misses are the ones the branch never changed. This check asks the other question directly.
So this check reads the merge itself (`git merge-tree --write-tree base head`) and reports:

for every path the base has that the branch does NOT change:
is the branch's copy byte-identical to the base's?
FAIL the merge conflicts, or it would leave a path the branch never changed different from the base's copy
(a real loss: the base's content would not survive);
note the branch is behind on N path(s) it never changed: the merge keeps the base's copies, but the branch's
own tests ran against the older ones, so rebase before trusting them.

A difference there cannot be the branch's intent -- it did not touch the file -- so it is a stale copy, and merging
it would write the old content over the base's. Files the branch does change are excluded, so a legitimate
divergence is never reported.
Paths changed on BOTH sides are where a conflict resolution can silently take the branch's side; this check does
not judge a resolution (compare it against both parents by hand, as on #2021/#2368).

Exit 0 quiet, 1 stale files found, 2 a ref could not be read (which is not a pass).
Exit 0 no loss, 1 a conflict or a lost base change, 2 a ref could not be read (which is not a pass).
"""

import argparse
Expand Down Expand Up @@ -69,7 +69,7 @@ def touched_by_branch(base, head, merge_base):


def main():
parser = argparse.ArgumentParser(description="Report files where the branch carries an older copy.")
parser = argparse.ArgumentParser(description="Report what merging the branch would lose from the base.")
parser.add_argument("--base", default="origin/main", help="base ref (default: origin/main)")
parser.add_argument("--head", default="HEAD", help="head ref (default: HEAD)")
parser.add_argument("--quiet", action="store_true", help="only print failures")
Expand Down Expand Up @@ -100,7 +100,7 @@ def main():
print("branch_stale_check: could not diff the branch against its merge base", file=sys.stderr)
return 2

stale = []
behind = []
added_by_base = []
for path in base_paths:
base_blob = blob_sha(args.base, path)
Expand All @@ -115,7 +115,18 @@ def main():
# that can only fire on the harmless case is an arm that would teach readers to ignore the check.
added_by_base.append(path)
elif base_blob != head_blob:
stale.append(path)
behind.append(path)

# engine#2410: what lands is the merge, not the branch's endpoint, so read the merge.
merged = git("merge-tree", "--write-tree", "--no-messages", args.base, args.head)
if merged.returncode not in (0, 1) or not merged.stdout.strip():
print(f"branch_stale_check: git merge-tree failed ({merged.stderr.strip()}) - cannot tell, and that is not a pass",
file=sys.stderr)
return 2
merged_lines = merged.stdout.splitlines()
merge_tree = merged_lines[0].strip()
conflicted = sorted({line.split("\t", 1)[1] for line in merged_lines[1:] if "\t" in line})
lost = [path for path in behind + added_by_base if blob_sha(merge_tree, path) != blob_sha(args.base, path)]

# 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
Expand All @@ -128,20 +139,28 @@ def main():
f"- commit them and re-run to check the branch you are handing over")

if not args.quiet:
print(f"branch_stale_check: base {args.base} {len(base_paths)} path(s), branch touches {len(touched)} of them; "
f"{len(stale)} older cop(ies) (the base also added {len(added_by_base)} path(s) the branch predates, "
f"which a merge supplies)")

for path in stale[: args.limit]:
print(f"FAIL branch_stale_check: {path} - the branch carries an older copy and never changed it")
if len(stale) > args.limit:
print(f"FAIL branch_stale_check: … and {len(stale) - args.limit} more older cop(ies)")
if stale:
print("branch_stale_check: rebase onto the base - a squash merge of this branch would write these older "
"copies over it", file=sys.stderr)
print(f"branch_stale_check: base {args.base} {len(base_paths)} path(s), branch touches {len(touched)}; "
f"behind on {len(behind)} it never changed (the base also added {len(added_by_base)} the branch "
f"predates); the merge keeps the base's copy of {len(behind) + len(added_by_base) - len(lost)} of them")

for path in conflicted[: args.limit]:
print(f"FAIL branch_stale_check: {path} - the merge with the base conflicts here")
for path in lost[: args.limit]:
print(f"FAIL branch_stale_check: {path} - the branch never changed it, yet the merge would not keep the "
f"base's copy")
if conflicted or lost:
print("branch_stale_check: rebase onto the base and resolve, then re-run", file=sys.stderr)
return 1
if behind and not args.quiet:
for path in behind[: args.limit]:
print(f"note branch_stale_check: {path} - behind the base (the merge keeps the base's copy)")
if len(behind) > args.limit:
print(f"note branch_stale_check: ... and {len(behind) - args.limit} more")
print("branch_stale_check: nothing the base has is lost by the merge; the branch's own tests ran against the "
"older copies above, so rebase before trusting them")
return 0
if not args.quiet:
print("branch_stale_check: no file the branch left alone differs from the base")
print("branch_stale_check: the merge keeps every base change the branch left alone")
return 0


Expand Down
Loading