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
5 changes: 3 additions & 2 deletions docs/pre-pr-checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ limitations under the License.
-->
# Before you ask for a merge

Nine commands, all host-side, none needing a device or a build. Every one of them answers a question that
Ten 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 eight**, one line each (`--base <ref>` for the registration check, `--list` to see the
**`scripts/pre-pr-checks.sh` runs the first nine**, 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
eighth 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. The table's order is the runner's order: cheapest and most common first, and the check that needs a revision
Expand All @@ -37,6 +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) |
| `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
1 change: 1 addition & 0 deletions scripts/pre-pr-checks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ checks=(
"tools/ci/submodule_pin_check.py --check"
"tools/ci/registration_loss_check.py --check --base $base"
"tools/ci/registry_loss_check.py --base $base"
"tools/ci/branch_stale_check.py --base $base"
)

# The page and this list drift apart, and it has happened twice in one night: the page said the runner "runs the first six"
Expand Down
7 changes: 7 additions & 0 deletions tests/branch_stale_check_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,13 @@ def test_a_file_the_base_added_and_the_branch_predates_is_not_a_failure(self):
self.assertIn("the base also added", result.stdout)
self.assertNotIn("added-after-the-fork.txt - the branch carries", result.stdout)

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.
git(self.repo, "checkout", "-q", "main")
self.write("shared.txt", "an uncommitted edit\n")
result = self.run_check(self.main, "HEAD")
self.assertIn("uncommitted path(s) are NOT included", result.stdout)

def test_an_unreadable_ref_refuses_instead_of_passing(self):
result = self.run_check(self.main, "no-such-ref")
self.assertEqual(result.returncode, 2, result.stdout + result.stderr)
Expand Down
10 changes: 10 additions & 0 deletions tools/ci/branch_stale_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,16 @@ def main():
elif base_blob != head_blob:
stale.append(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
# 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")

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, "
Expand Down
Loading