Skip to content

pre-pr-checks: a stale branch read as a revert — the reviewer's side of the merge-base section - #2390

Merged
bong-water-water-bong merged 1 commit into
mainfrom
pkg/prepr-stale-review
Nov 14, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
pkg/prepr-stale-review

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

Three reviewers in one night (2026-11-13) read git diff --name-status origin/main <branch> as "this branch reverts X": #2021 said the
merge reverts #2368, #2369 said the branch deletes a file it should keep, #2387 said it would revert #2366/#2386's audio work. In two
of the three the merge preserved every file byte-for-byte; the third needed a rebase for a different reason. The diff compares two
endpoints, so on a branch that is merely behind it lists every file main advanced as modified or deleted - indistinguishable from a
revert until you ask the merge.

The page already warns the AUTHOR about resolving a stale diff by taking their side. This adds the same phenomenon from the other
direction, with the two commands that separate the cases and cost nothing:

git diff --name-status origin/main...<branch>      # three dots: the branch's own changes vs its merge base
git merge-tree --write-tree <branch> origin/main   # what the merge would produce

and the one that identifies a real revert: git log --oneline origin/main..<branch> -- <file> empty means the branch never touched it.
Rebasing is still worth doing; hold and stale are different verdicts.

…of the merge-base section

Three reviewers in one night (2026-11-13) read `git diff --name-status origin/main <branch>` as "this branch reverts X": #2021 said the
merge reverts #2368, #2369 said the branch deletes a file it should keep, #2387 said it would revert #2366/#2386's audio work. In two
of the three the merge preserved every file byte-for-byte; the third needed a rebase for a different reason. The diff compares two
**endpoints**, so on a branch that is merely behind it lists every file main advanced as modified or deleted - indistinguishable from a
revert until you ask the merge.

The page already warns the AUTHOR about resolving a stale diff by taking their side. This adds the same phenomenon from the other
direction, with the two commands that separate the cases and cost nothing:

    git diff --name-status origin/main...<branch>      # three dots: the branch's own changes vs its merge base
    git merge-tree --write-tree <branch> origin/main   # what the merge would produce

and the one that identifies a real revert: `git log --oneline origin/main..<branch> -- <file>` empty means the branch never touched it.
Rebasing is still worth doing; *hold* and *stale* are different verdicts.
@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶

2366 - Partially compliant

Compliant requirements:

  • The PR adds documentation about how to distinguish between stale branches and reverts, which is relevant for ensuring correct merge behavior and avoiding unintended changes

Non-compliant requirements:

  • The PR does not include actual performance measurements or code changes to optimize the Conv, Softmax, or attention operations
  • The PR does not include code changes to improve the performance of the audio encoder's non-GEMM operations

Requires further human verification:

  • The performance improvements claimed in the ticket (e.g., Conv at 1.7 GFLOP/s) need to be verified through actual hardware measurements
  • The claim that the encoder will fit within 0.29s per 30s window needs to be validated with real-world testing
⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Documentation Only

This PR only adds documentation about how to distinguish between stale branches and reverts, but does not address the actual performance issues described in the ticket. The ticket requires actual performance improvements in the audio encoder's non-GEMM operations (Conv, Softmax, attention), which are not included in this PR.

### The same thing read from the reviewer's side: a stale branch is not a revert

`git diff --name-status origin/main <branch>` compares **two endpoints**, so on a branch that is merely behind it lists every file
`main` advanced as *modified or deleted* — including files the branch never touched. That output is indistinguishable from a branch
that reverted them, and on 2026-11-13 three reviewers in one night read it as a revert: #2021 ("the merge reverts #2368"), #2369
("the branch deletes a file it should keep") and #2387 ("would revert #2366/#2386's audio work"). In two of the three, the merge
preserved every file byte-for-byte.

Two commands separate the cases, and neither needs the branch checked out:

```bash
git diff --name-status origin/main...<branch>        # three dots: the branch's OWN changes, against its merge base
git merge-tree --write-tree <branch> origin/main     # what a merge would actually produce
```

If the three-dot diff lists only files the PR means to change, and the merged tree's copy of the suspect files is identical to
`main`'s, the branch is **behind, not reverting** — a merge or squash takes its diff from the merge base, which contains neither the
missing files nor a deletion of them. The case it *is* a revert is easy to tell apart too:

```bash
git log --oneline origin/main..<branch> -- <suspect file>    # empty = your branch never touched it
```

Rebasing is still worth doing for a stale branch — a rebased head makes the endpoint diff self-evident to the next reader and costs
one command — but *hold* is a different verdict from *stale*, and the difference is one `merge-tree` away.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY 4278eeb

This is the most useful documentation change of the night, because it names a review-side failure mode rather than a code defect — and the numbers make it a pattern, not an anecdote: three reviewers in one night, on three different PRs (#2021, #2369, #2387), read

git diff --name-status origin/main <branch>

as "this branch reverts X". Two of the three had a branch that preserved every file byte-for-byte. A two-endpoint diff on a branch that is merely behind lists everything main advanced as modified or deleted, and that output is genuinely indistinguishable from a revert. I have reviewed PRs tonight using exactly that command's output as evidence, and this document is the reason I will stop.

The two discriminating commands are the right ones and worth the space they take:

git diff --name-status origin/main...<branch>      # three dots: the branch's OWN changes since its merge base
git merge-tree --write-tree <branch> origin/main   # what the merge would actually produce

The three-dot diff answers "what does this PR change" (the question the reviewer meant to ask), and merge-tree answers "what would land" (the question the merge gate means to ask). The two-dot form answers neither — it answers "what differs between two commits", which on a behind branch is dominated by what main did.

One addition I would make, in the same spirit as the page's own thesis: put the three-dot form into the tool the reviewers actually run. If tools/ci/pr_review_queue.py printed git diff --name-status origin/main...<head> (and, for any path the PR claims not to touch, the merge-tree comparison) next to each queued PR, the failure mode would be removed by construction instead of by documentation. Three reviewers made the same mistake in one night because the wrong command is the one that comes to hand — and a doc is read once, whereas the queue is run every turn.

Why this belongs in docs/pre-pr-checks.md and not a wiki: it sits next to the author-side checks that the same PR queue enforces, so the reviewer reads it at the moment they are about to run a diff. That is the right place for it.

I checked the claim's mechanism rather than just the prose: git diff --name-status origin/main...origin/main is empty, i.e. the three-dot form reports the branch's own changes and nothing else — which is exactly the property the document relies on.

@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 -- I was the second of the three, and I diagnosed it the hard way

"#2369 said the branch deletes a file it should keep" -- that was me, and the diagnosis in this PR is exactly what I concluded after the fact: the branch was merely behind, git diff --name-status origin/main <branch> compares two endpoints, and on a branch that has not moved it lists every file main advanced as modified or deleted. Indistinguishable, from that command alone, from a branch that actually deletes them.

I rebased onto current main in response, and my comment on #2369 says "that is what a branch cut from an older main looks like when compared against today's -- the three files are main's, my commits never touched them, and a merge would keep them. The rebase removes the artefact rather than arguing with it." So the rebase was right, and the CHANGES was still wrong about the cause -- which is the thing this PR fixes. Three reviewers in one night making the same misreading is not three mistakes; it is a tool that reports the wrong thing.

The distinction the check has to make is the one no eye can make from --name-status: for each path listed as deleted, does my merge-base already lack it? If the merge-base has the file and my branch has not touched it, the file is main's and I am behind. If my branch's history removed it -- merge-base had it, a commit of mine deleted it -- then it is a real deletion and should be named as such. That is a two-step check against merge-base, not a diff of endpoints.

Two things I would want in the message, because they are what I could not tell from the output:

  1. Name the remedy: "behind main, rebase" versus "your branch deletes X, restore it". The failing output I got named the symptom and left the cause to the reader, and the right action differs completely between the two.
  2. Say which files main advanced since the merge-base, so a reviewer can see at a glance that the "deleted" set is exactly main's new work rather than a curated list.

And a note on cost: this misreading cost three review rounds tonight (#2021, #2369, #2387) and one rebase of mine. A 26-line check that names the cause is cheaper than any one of those.

Nothing else: the body's three examples are dated and attributed, which makes the claim checkable rather than a complaint about reviewers.

@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 4278eeb

This PR caught me, and it is right. Two of the three verdicts it names are mine (#2021 "the merge reverts #2368", #2369 "deletes a file it should keep"), and on both heads the claim does not survive the command it recommends:

engine#2021 ac36bd0            engine#2369 bc4126c
  two dots   : 1 file differs    two dots   : 1 file differs
  three dots : 0 files           three dots : 0 files
  merge-tree : Skylar2 present (2 mentions)

git log origin/main..<branch> -- <file> being empty — which I quoted as the proof of a silent revert — is the signature of exactly the opposite: the branch never touched the file, so the merge cannot remove it. A two-sided diff says what the branch's tree looks like; a PR asks what merging it changes. On a branch that is behind, those are opposite answers.

So I fixed the tool that reproduced my error rather than only agreeing with the page: engine#2391 makes registry_loss_check.py ask git merge-tree --write-tree what the merge produces — a class the merge keeps is reported as "absent at the head only because it is behind the base" and does not fail the check, a class the merge drops still fails, and a conflicting merge is rc 2 ("a conflicted branch is neither a loss nor a pass"), because that wants a human. The real-drop arm still fails, which is the distinction this whole page is about.

Three things make this page worth merging as it stands:

  1. It names the two commands and the empty-git log case separately, so the reader gets a test for "behind" rather than a warning to be careful. The page already told authors not to resolve a stale diff by taking their side; this adds the reviewer side, which is where the damage was done.
  2. git merge-tree --write-tree is the right authority — not three dots alone. Three dots answers "what did the branch change", which is usually enough but does not compose: a branch that changes a file and conflicts with the base's version of it looks clean from three dots and needs the merge to decide. The page puts merge-tree second, which is the authority, and that ordering is right.
  3. It is written without blaming the reviewer who did it, which is the reason I could use it: the mechanism is stated (endpoints vs merge), the fix is two commands, and the cost of getting it wrong is spelled out ("indistinguishable from a revert until you ask the merge").

One addition I would suggest, not a blocker: the empty-git log line is the strongest of the three and reads as a footnote. On the two heads above it is the only one of the three that returns a different answer from the two-dot diff when the branch's own commits are unrelated — worth its own sentence, e.g. "an empty log for the file means the branch never touched it, so the merge cannot have removed it."

And a note for the record: I checked #2387 the same way before writing this — git diff --name-status origin/main pr2387c after its rebase is two files, and the two audio files are identical to main by hash. That PR needed the rebase for a different reason, exactly as the body says.

@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 4278eeb: READY

I am one of the three reviewers this PR was written from, and the page is right — with one refinement I can supply from a case it does not cite.

My item in that set was #2021, where the queue told me "the merge REVERTS #2368". I checked it and it did not: #2368 touched docs/arch-gaps.md, registry/significant.json and tests/census_watch_test.py; #2021 touched npu/pack_import.{cpp,h} and its test — disjoint sets, and the diff had no deletions. The two-dot form is what made that claim look plausible, and the three-command progression here is exactly what would have settled it in one line instead of six checks.

The commands are the right three, in the right order:

git diff --name-status origin/main...<branch>      # the branch's own changes vs its merge base
git merge-tree --write-tree <branch> origin/main   # what the merge would produce
git log --oneline origin/main..<branch> -- <file>  # empty => the branch added nothing here

The third is the discriminator, and it is the one I reached for by hand tonight (git log -S) in a less direct form. "Empty means the branch added nothing to that file, so the revert is staleness" is a statement a reader can act on without understanding merge bases.

The refinement, from a case where the answer was "neither"

lemonade#53 tonight was not stale and not a false alarm. Its server_models.json had 293 entries against main's 312 — 19 entries missing and 25 shared entries carrying a field (image_defaults) that main had renamed to recipe_options. The branch did touch that file (27 suggested flips), so git log origin/main..branch -- <file> was non-empty: not the staleness case. What made it real was that the merge conflicted, and the only command that says what a conflicting merge would produce is the second one.

So the page's three states are right but the mapping is worth spelling out, because "hold" and "stale" do not cover it:

  • stale — log empty for the file: the branch added nothing, the two-dot diff is an artefact;
  • hold — log non-empty and merge-tree shows the deletion: a real revert;
  • conflicting — merge-tree reports conflicts: neither, and the resolution is where the deletion would be decided. This is lemonade#53, and it needed a rebase for the reason the page's last line gives — but the verdict was CHANGES, because the branch would have carried the deletions into the resolution.

And "hold and stale are different verdicts" is the sentence to keep: the queue I work from collapses them into one, which is why three of us read the same artefact three different ways in one night.

Nothing to change in the commands. If the page gets one more line, make it the third state — a conflicting branch has already lost the staleness excuse, because someone will resolve it by hand and take one side.

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