Skip to content

Commit 3b5bf0f

Browse files
authored
Lint only what a PR adds: diff the link checks from the merge base (pytorch#21765)
### Summary The URL, xref, and file-size linters diffed `base..head`, where `base` is the **tip** of the base branch rather than the point the branch left it. A branch cut before recent commits still carries the lines those commits replaced, so against the newer tip its old copies read as additions, and the branch gets blamed for links someone else already repaired. pytorch#21729 failed exactly this way. It touches 18 files and adds no URLs at all, but the two-dot diff scoped the lint to 143 files and flagged nine links that pytorch#21694 had already fixed or `@lint-ignore`d. pytorch#21707 is starker: one Python file with no URLs in it, 199 files linted, the same nine failures. ``` base..head 143 files <- what CI linted base...head 18 files <- what the PR actually changes ``` The stray `jq: parse error` lines in pytorch#21729's log are the same symptom from the other direction: the job runs the branch's own pre-pytorch#21694 copy of `lint_urls.sh`. ### Fix The workflow resolves the merge base and passes it down. That is the half that matters for branches already open: on a `pull_request` the reusable workflow resolves from the merge commit, so it carries this fix even though `scripts/` still comes from the branch itself. The scripts also switch to three-dot ranges so `./scripts/lint_urls.sh main HEAD` by hand behaves the same. `lint_xrefs.sh` and `lint_file_size.sh` had the identical bug and get the identical change. **Cost, stated plainly.** A merge base needs real history, so this restores `fetch-depth: 0` on the `pull_request` path — line for line what pytorch#17682 removed in February for speed. Measured on this branch, that is ~25s of added wall clock and ~79s of runner time across the three concurrent jobs. pytorch#17682's 6min → 10s was mostly the runner and Docker change rather than the fetch depth, though the commit changes both at once and I can't fully separate them. Pushes and the nightly whole-tree scan cannot use a merge base and stay shallow: ```yaml fetch-depth: ${{ github.event_name == 'pull_request' && '0' || '1' }} ``` The quotes matter — bare `0` is falsy in GitHub expressions, so `&& 0 || 1` always yields `1` and would silently disable the fix. **No silent fallback.** When there is no merge base there is no usable range, so the range is left unset and the linters scan the whole tree. Substituting the base tip instead produces a range the scripts fail on quietly: verified against unrelated histories, `lint_urls.sh` and `lint_xrefs.sh` both exit **0** having checked nothing, while `lint_file_size.sh` exits 128 and the wrapper reports "some files exceed the 1 MB limit", which is not what happened. Unset args are loud instead — verified rc=1 on a tree containing a dead link. **`--no-color`.** Both `git diff` calls now pass it, matching the `git grep --no-color` two lines below. With `color.ui = always` in a developer's config, added lines arrive wrapped in escape sequences, `grep -E '^\+'` matches nothing, and the check passes having found nothing (measured: 2 matches → 0). ### Test plan `.ci/scripts/tests/test_link_check_diff_selection.py` builds a diverged history where `main` repairs bad links and shrinks an oversized file while the feature branch simply predates all of it. Four fixture files each pin a different part, and `curl` is stubbed so there is no network: | Fixture | Pins | |---|---| | `both_sides.md` — edited on both branches | the per-file diff range | | `big.bin` — oversized at the branch point, shrunk on main | `lint_file_size.sh`'s range | | `colorful.gitconfig` — `color.ui = always` | `--no-color` | | `base_only.md` / `feature_only.md` | that main-only changes stay invisible and the branch's own additions are still checked | ``` pytest .ci/scripts/tests/test_link_check_diff_selection.py # 4 passed ``` Mutating each changed line individually: ``` inner per-file range -> .. 3 failed caught lint_file_size range -> .. 1 failed caught drop --no-color 1 failed caught file-selection range -> .. 4 passed equivalent mutant, see below ``` The file-selection range is not pinned because it cannot be: with the per-file diff at three dots, the extra files it selects produce empty diffs. Replayed against pytorch#21707's real 199-file range, both variants emit byte-identical output. It is changed for consistency, not behaviour. **Narrowing the scope must not blunt the check**, so each linter also has a positive control where the branch itself adds the bad thing: ``` lint_urls adds a dead URL -> rc=1, reports example.invalid/dead lint_xrefs adds a broken reference -> rc=1, reports sub/missing.md lint_file_size adds a 1MB+ file -> rc=1, reports feature_big.bin ``` End to end on real content: a synthetic commit on top of `main` that puts pytorch#21694's nine repaired links back, as if a PR had added them, gives `rc=1` with 9 FAIL and 5 OK against the live network. Incidentally `musl.cc` answered this time where CI saw `000`, and `pybind/cmake_example` now 404s where CI saw `301` — which is the retry-then-WARN path earning its keep. Also replayed pytorch#21729's and pytorch#21707's exact CI refs through the fixed scripts (exit 0 each), and ran all three linters plus `lintrunner` against this PR's own diff. ### Known limitations - The checkout is `head.sha`, so references still resolve against the branch tree rather than the merge result — the mirror image of the bug fixed here. Pre-existing and not worsened by this PR. - The whole-tree branch swallows a `git grep` failure and exits 0, so on a git built without PCRE the scan silently checks nothing. Reachable locally, not on the runners, which is why the nightly scan works. Pre-existing; worth a follow-up rather than widening this PR. ### Rollout This does **not** repair a currently red run. A rerun keeps the original `GITHUB_SHA`, and advancing the base alone does not fire `synchronize`, so an already-open PR picks the fix up only on its next newly triggered pull-request run — any push, or close/reopen. That is still cheaper than a content rebase: no history rewrite, no conflicts, nothing to re-review. Supersedes pytorch#21762, which fixes the same bug but leaves the checkout shallow and misses `lint_urls.sh`. Its reviewer's shallow-checkout point is exactly right: a `--depth=1` fetch writes a shallow graft even into an otherwise complete clone, after which `git merge-base` fails and `A...B` is fatal, so the two halves of this change are a pair. The regression test here is adapted from that PR. Authored with Claude Code (Claude Opus 5).
1 parent b897b19 commit 3b5bf0f

5 files changed

Lines changed: 225 additions & 13 deletions

File tree

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
import os
8+
import shutil
9+
import subprocess
10+
import sys
11+
import tempfile
12+
import unittest
13+
from pathlib import Path
14+
15+
import pytest
16+
17+
REPO_ROOT = Path(__file__).resolve().parents[3]
18+
19+
# Fixture content, not real references. The linters under test would otherwise find
20+
# their own bait here and check it against this repo.
21+
BAD = "[broken](sub/missing.md)\nhttps://example.invalid/dead\n" # @lint-ignore
22+
GOOD = "[fine](sub/present.md)\nhttps://example.invalid/live\n" # @lint-ignore
23+
24+
OVERSIZED = "x" * (1024 * 1024 + 1)
25+
26+
CURL_STUB = """#!/bin/sh
27+
for arg in "$@"; do url=$arg; done
28+
case "$url" in *dead*) echo 404 ;; *) echo 200 ;; esac
29+
"""
30+
31+
32+
@pytest.mark.skipif(sys.platform == "win32", reason="The scripts under test need bash")
33+
class TestLinkCheckDiffSelection(unittest.TestCase):
34+
"""A branch cut before recent base commits keeps the base branch's old lines. Those
35+
are not the branch's to answer for, so the linters must diff from the merge base.
36+
37+
Each fixture file pins a different part of that: base_only.md the file selection,
38+
both_sides.md the per-file diff, big.bin the file size range, feature_only.md that
39+
the branch's own additions are still checked at all.
40+
"""
41+
42+
def setUp(self):
43+
self.repo = Path(tempfile.mkdtemp())
44+
self.addCleanup(shutil.rmtree, self.repo, ignore_errors=True)
45+
self.git("init", "-q")
46+
self.git("symbolic-ref", "HEAD", "refs/heads/main")
47+
self.git("config", "user.email", "test@example.com")
48+
self.git("config", "user.name", "test")
49+
50+
self.write("sub/present.md", "target\n")
51+
self.write("base_only.md", BAD)
52+
self.write("both_sides.md", BAD)
53+
self.write("big.bin", OVERSIZED)
54+
self.commit("initial")
55+
self.git("branch", "feature")
56+
57+
self.write("base_only.md", GOOD)
58+
self.write("both_sides.md", GOOD)
59+
self.write("big.bin", "small\n")
60+
self.commit("main repairs the links and shrinks the file")
61+
62+
self.git("checkout", "-q", "feature")
63+
self.write("both_sides.md", BAD + GOOD)
64+
self.write("feature_only.md", GOOD)
65+
self.commit("feature edits one file and adds another")
66+
67+
def env(self, **extra):
68+
# A developer's git config and any inherited GIT_DIR must not reach the fixture.
69+
env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
70+
env["GIT_CONFIG_GLOBAL"] = os.devnull
71+
env["GIT_CONFIG_SYSTEM"] = os.devnull
72+
env.update(extra)
73+
return env
74+
75+
def git(self, *args):
76+
subprocess.run(
77+
["git", *args],
78+
cwd=self.repo,
79+
check=True,
80+
capture_output=True,
81+
env=self.env(),
82+
)
83+
84+
def write(self, relpath, text):
85+
path = self.repo / relpath
86+
path.parent.mkdir(parents=True, exist_ok=True)
87+
path.write_text(text)
88+
89+
def commit(self, message):
90+
self.git("add", "-A")
91+
self.git("commit", "-q", "-m", message)
92+
93+
def add_on_feature(self, relpath, text):
94+
self.write(relpath, text)
95+
self.commit(f"feature adds {relpath}")
96+
97+
def lint(self, script, **env):
98+
return subprocess.run(
99+
["bash", str(REPO_ROOT / "scripts" / script), "main", "feature"],
100+
cwd=self.repo,
101+
capture_output=True,
102+
text=True,
103+
env=self.env(**env),
104+
)
105+
106+
def assert_scoped_to_feature(self, result):
107+
output = result.stdout + result.stderr
108+
self.assertEqual(result.returncode, 0, output)
109+
self.assertIn("feature_only.md", result.stdout)
110+
self.assertIn("both_sides.md", result.stdout)
111+
self.assertNotIn("base_only.md", output)
112+
113+
def curl_stub(self):
114+
stub_dir = self.repo / "stub"
115+
stub_dir.mkdir()
116+
stub = stub_dir / "curl"
117+
stub.write_text(CURL_STUB)
118+
stub.chmod(0o755)
119+
return {"PATH": f"{stub_dir}{os.pathsep}{os.environ['PATH']}"}
120+
121+
def test_lint_urls_ignores_lines_the_branch_only_lacks(self):
122+
self.assert_scoped_to_feature(self.lint("lint_urls.sh", **self.curl_stub()))
123+
124+
def test_lint_xrefs_ignores_lines_the_branch_only_lacks(self):
125+
self.assert_scoped_to_feature(self.lint("lint_xrefs.sh"))
126+
127+
def test_lint_file_size_ignores_files_the_branch_only_lacks(self):
128+
result = self.lint("lint_file_size.sh")
129+
output = result.stdout + result.stderr
130+
self.assertEqual(result.returncode, 0, output)
131+
self.assertIn("feature_only.md", result.stdout)
132+
self.assertNotIn("big.bin", output)
133+
134+
def test_lint_urls_still_catches_a_url_the_branch_adds(self):
135+
self.add_on_feature("feature_bad.md", BAD)
136+
result = self.lint("lint_urls.sh", **self.curl_stub())
137+
output = result.stdout + result.stderr
138+
self.assertEqual(result.returncode, 1, output)
139+
self.assertIn("example.invalid/dead", output)
140+
141+
def test_lint_xrefs_still_catches_a_reference_the_branch_adds(self):
142+
self.add_on_feature("feature_bad.md", BAD)
143+
result = self.lint("lint_xrefs.sh")
144+
output = result.stdout + result.stderr
145+
self.assertEqual(result.returncode, 1, output)
146+
self.assertIn("sub/missing.md", output)
147+
148+
def test_lint_file_size_still_catches_a_file_the_branch_adds(self):
149+
self.add_on_feature("feature_big.bin", OVERSIZED)
150+
result = self.lint("lint_file_size.sh")
151+
output = result.stdout + result.stderr
152+
self.assertEqual(result.returncode, 1, output)
153+
self.assertIn("feature_big.bin", output)
154+
155+
def test_lint_urls_survives_a_colorizing_git_config(self):
156+
config = self.repo / "colorful.gitconfig"
157+
config.write_text("[color]\n\tui = always\n")
158+
result = self.lint(
159+
"lint_urls.sh", GIT_CONFIG_GLOBAL=str(config), **self.curl_stub()
160+
)
161+
self.assert_scoped_to_feature(result)

‎.github/workflows/_link_check.yml‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ on:
55
type: string
66
required: true
77
base_ref:
8-
description: Commit to diff against. Empty, or all zeros, means check the whole tree.
8+
description: >
9+
Base branch commit. Pull requests lint from its merge base with ref, pushes
10+
lint from it directly. Empty, or all zeros, means check the whole tree.
911
type: string
1012
required: false
1113
default: ''
@@ -21,16 +23,31 @@ jobs:
2123
- uses: actions/checkout@v4
2224
with:
2325
ref: ${{ inputs.ref }}
26+
# Only the merge base path needs history, and it costs ~25s. Quote the
27+
# branches: bare 0 is falsy, so `&& 0 || 1` would always yield 1.
28+
fetch-depth: ${{ github.event_name == 'pull_request' && '0' || '1' }}
2429
- name: Lint URLs
2530
env:
2631
BASE_REF: ${{ inputs.base_ref }}
2732
HEAD_REF: ${{ inputs.ref }}
33+
FROM_MERGE_BASE: ${{ github.event_name == 'pull_request' }}
2834
run: |
2935
args=()
3036
# A push creating a tag or branch reports an all zero SHA no remote can serve.
3137
if [ -n "$BASE_REF" ] && [ "$BASE_REF" != "0000000000000000000000000000000000000000" ]; then
32-
git fetch --no-tags --depth=1 origin "$BASE_REF"
33-
args=("$BASE_REF" "$HEAD_REF")
38+
if [ "$FROM_MERGE_BASE" = "true" ]; then
39+
git fetch --no-tags origin "$BASE_REF"
40+
# Where the branch left the base branch, not the base branch tip, or a
41+
# branch cut before recent commits is blamed for every line it merely
42+
# lacks. No merge base means no usable range, so leave args empty for a
43+
# whole tree scan: the scripts treat a bad range as nothing to check.
44+
if merge_base=$(git merge-base "$BASE_REF" "$HEAD_REF"); then
45+
args=("$merge_base" "$HEAD_REF")
46+
fi
47+
else
48+
git fetch --no-tags --depth=1 origin "$BASE_REF"
49+
args=("$BASE_REF" "$HEAD_REF")
50+
fi
3451
fi
3552
./scripts/lint_urls.sh "${args[@]}" || {
3653
echo
@@ -50,16 +67,31 @@ jobs:
5067
- uses: actions/checkout@v4
5168
with:
5269
ref: ${{ inputs.ref }}
70+
# Only the merge base path needs history, and it costs ~25s. Quote the
71+
# branches: bare 0 is falsy, so `&& 0 || 1` would always yield 1.
72+
fetch-depth: ${{ github.event_name == 'pull_request' && '0' || '1' }}
5373
- name: Lint cross-references
5474
env:
5575
BASE_REF: ${{ inputs.base_ref }}
5676
HEAD_REF: ${{ inputs.ref }}
77+
FROM_MERGE_BASE: ${{ github.event_name == 'pull_request' }}
5778
run: |
5879
args=()
5980
# A push creating a tag or branch reports an all zero SHA no remote can serve.
6081
if [ -n "$BASE_REF" ] && [ "$BASE_REF" != "0000000000000000000000000000000000000000" ]; then
61-
git fetch --no-tags --depth=1 origin "$BASE_REF"
62-
args=("$BASE_REF" "$HEAD_REF")
82+
if [ "$FROM_MERGE_BASE" = "true" ]; then
83+
git fetch --no-tags origin "$BASE_REF"
84+
# Where the branch left the base branch, not the base branch tip, or a
85+
# branch cut before recent commits is blamed for every line it merely
86+
# lacks. No merge base means no usable range, so leave args empty for a
87+
# whole tree scan: the scripts treat a bad range as nothing to check.
88+
if merge_base=$(git merge-base "$BASE_REF" "$HEAD_REF"); then
89+
args=("$merge_base" "$HEAD_REF")
90+
fi
91+
else
92+
git fetch --no-tags --depth=1 origin "$BASE_REF"
93+
args=("$BASE_REF" "$HEAD_REF")
94+
fi
6395
fi
6496
./scripts/lint_xrefs.sh "${args[@]}" || {
6597
echo
@@ -79,16 +111,31 @@ jobs:
79111
- uses: actions/checkout@v4
80112
with:
81113
ref: ${{ inputs.ref }}
114+
# Only the merge base path needs history, and it costs ~25s. Quote the
115+
# branches: bare 0 is falsy, so `&& 0 || 1` would always yield 1.
116+
fetch-depth: ${{ github.event_name == 'pull_request' && '0' || '1' }}
82117
- name: Lint file sizes
83118
env:
84119
BASE_REF: ${{ inputs.base_ref }}
85120
HEAD_REF: ${{ inputs.ref }}
121+
FROM_MERGE_BASE: ${{ github.event_name == 'pull_request' }}
86122
run: |
87123
args=()
88124
# A push creating a tag or branch reports an all zero SHA no remote can serve.
89125
if [ -n "$BASE_REF" ] && [ "$BASE_REF" != "0000000000000000000000000000000000000000" ]; then
90-
git fetch --no-tags --depth=1 origin "$BASE_REF"
91-
args=("$BASE_REF" "$HEAD_REF")
126+
if [ "$FROM_MERGE_BASE" = "true" ]; then
127+
git fetch --no-tags origin "$BASE_REF"
128+
# Where the branch left the base branch, not the base branch tip, or a
129+
# branch cut before recent commits is blamed for every line it merely
130+
# lacks. No merge base means no usable range, so leave args empty for a
131+
# whole tree scan: the scripts treat a bad range as nothing to check.
132+
if merge_base=$(git merge-base "$BASE_REF" "$HEAD_REF"); then
133+
args=("$merge_base" "$HEAD_REF")
134+
fi
135+
else
136+
git fetch --no-tags --depth=1 origin "$BASE_REF"
137+
args=("$BASE_REF" "$HEAD_REF")
138+
fi
92139
fi
93140
chmod +x ./scripts/lint_file_size.sh
94141
./scripts/lint_file_size.sh "${args[@]}" || {

‎scripts/lint_file_size.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ is_exception() {
4040
if [ $# -eq 2 ]; then
4141
base=$1
4242
head=$2
43-
echo "Checking changed files between $base..$head"
44-
files=$(git diff --name-only "$base..$head")
43+
echo "Checking changed files between $base...$head"
44+
files=$(git diff --no-color --name-only "$base...$head")
4545
else
4646
echo "Checking all files in repository"
4747
files=$(git ls-files)

‎scripts/lint_urls.sh‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,10 @@ done < <(
7070
':(exclude,glob)**/third_party/**'
7171
)
7272
if [ $# -eq 2 ]; then
73-
for filename in $(git diff --name-only --unified=0 "$1..$2"); do
74-
git diff --unified=0 "$1..$2" -- "$filename" "${excludes[@]}" \
73+
# Three dots, not two. Against the base branch tip, a branch cut before recent
74+
# commits looks like it is adding back every line those commits touched.
75+
for filename in $(git diff --no-color --name-only --unified=0 "$1...$2"); do
76+
git diff --no-color --unified=0 "$1...$2" -- "$filename" "${excludes[@]}" \
7577
| grep -E '^\+' \
7678
| grep -Ev '^\+\+\+' \
7779
| perl -nle 'print for m#'"$pattern"'#g' \

‎scripts/lint_xrefs.sh‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,10 @@ done < <(
3535
':(exclude,glob)**/third_party/**'
3636
)
3737
if [ $# -eq 2 ]; then
38-
for filename in $(git diff --name-only --unified=0 "$1..$2"); do
39-
git diff --unified=0 "$1..$2" -- "$filename" "${excludes[@]}" \
38+
# Three dots, not two. Against the base branch tip, a branch cut before recent
39+
# commits looks like it is adding back every line those commits touched.
40+
for filename in $(git diff --no-color --name-only --unified=0 "$1...$2"); do
41+
git diff --no-color --unified=0 "$1...$2" -- "$filename" "${excludes[@]}" \
4042
| grep -E '^\+' \
4143
| grep -Ev '^\+\+\+' \
4244
| perl -nle 'print for m#'"$pattern"'#g' \

0 commit comments

Comments
 (0)