Skip to content

Commit e9bfbbc

Browse files
committed
Check only new links in pull requests
1 parent ded8541 commit e9bfbbc

3 files changed

Lines changed: 106 additions & 0 deletions

File tree

‎.github/workflows/test.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@ jobs:
2525
if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
2626
runs-on: ubuntu-latest
2727
timeout-minutes: 20
28+
permissions:
29+
contents: read
30+
# actions:read is enough to restore the cache but saving the base
31+
# linkcheck results on pushes to main needs actions:write
32+
actions: write
2833
continue-on-error: >-
2934
${{ fromJSON(matrix.continue-on-error) }}
3035
strategy:
@@ -54,13 +59,58 @@ jobs:
5459
run: |
5560
python -m pip install --upgrade nox virtualenv
5661
62+
- name: Restore base linkcheck results
63+
# On PRs and merge queue runs, only check links added by the change
64+
# See https://github.com/pypa/packaging.python.org/issues/2037
65+
if: >-
66+
matrix.noxenv == 'linkcheck' &&
67+
contains(fromJSON('["pull_request", "merge_group"]'), github.event_name)
68+
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
69+
with:
70+
path: .cache/linkcheck-base
71+
# We don't expect an exact match here. Restore the most recent base
72+
# result using the restore-keys prefix instead
73+
key: linkcheck-base-${{ github.sha }}
74+
restore-keys: |
75+
linkcheck-base-
76+
5777
- name: Nox ${{ matrix.noxenv }}
5878
env:
5979
# Authenticate github.com requests during linkcheck to avoid rate limits.
6080
GITHUB_TOKEN: ${{ matrix.noxenv == 'linkcheck' && github.token || '' }}
6181
run: |
6282
python -m nox -s ${{ matrix.noxenv }}
6383
84+
- name: Prepare base linkcheck results
85+
# Only cache results from main so PRs and merge queue runs can compare
86+
# their links against the latest merged version.
87+
#
88+
# Keep this step running even if linkcheck finds broken links. It uses
89+
# --keep-going, so output.json still contains the full result set.
90+
# Broken links on main should be cached too, since they are already
91+
# known failures. Skip only if the run was cancelled or output.json
92+
# was never created.
93+
if: >-
94+
(success() || failure()) && matrix.noxenv == 'linkcheck' &&
95+
github.event_name == 'push' && github.ref == 'refs/heads/main'
96+
run: |
97+
mkdir -p .cache/linkcheck-base
98+
if [ -f build/output.json ]; then
99+
cp build/output.json .cache/linkcheck-base/output.json
100+
else
101+
echo "::warning::build/output.json not found; skipping base linkcheck cache update"
102+
fi
103+
104+
- name: Save base linkcheck results
105+
if: >-
106+
(success() || failure()) && matrix.noxenv == 'linkcheck' &&
107+
github.event_name == 'push' && github.ref == 'refs/heads/main' &&
108+
hashFiles('.cache/linkcheck-base/output.json') != ''
109+
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
110+
with:
111+
path: .cache/linkcheck-base
112+
key: linkcheck-base-${{ github.sha }}
113+
64114

65115
check:
66116
# This job does nothing and is only used for the branch protection

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
build/
2+
.cache/
23
.*~
34
.nox
45
*.pyc

‎source/conf.py‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# -- Project information ---------------------------------------------------------------
22
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
33

4+
import json
45
import os
56
import pathlib
7+
import re
68
import sys
79

810
_ROOT = pathlib.Path(__file__).resolve().parent.parent
@@ -184,6 +186,59 @@
184186
"https://api.github.com/": {"Authorization": f"Bearer {_gh_token}"},
185187
}
186188

189+
# On pull requests and merge queue runs only newly added links should be
190+
# checked, links already present on the base branch are ignored so existing
191+
# broken links don't cause the PR to fail.
192+
# Ref: https://github.com/pypa/packaging.python.org/issues/2037
193+
_LINKCHECK_PR_EVENT_NAMES = frozenset({"pull_request", "merge_group"})
194+
_BASE_LINKCHECK_OUTPUT = _ROOT / ".cache" / "linkcheck-base" / "output.json"
195+
196+
197+
def _iter_uris_from_linkcheck_jsonl(jsonl_path):
198+
"""Yield each ``uri`` from a linkcheck JSON Lines output file
199+
200+
Skip missing files and invalid lines so the build can still run when no
201+
base result has been cached yet or the output is incomplete.
202+
"""
203+
if not jsonl_path.is_file():
204+
return
205+
for line in jsonl_path.read_text(encoding="utf-8").splitlines():
206+
line = line.strip()
207+
if not line:
208+
continue
209+
try:
210+
record = json.loads(line)
211+
except json.JSONDecodeError:
212+
continue
213+
if not isinstance(record, dict):
214+
continue
215+
uri = record.get("uri")
216+
if uri:
217+
yield uri
218+
219+
220+
def _historic_linkcheck_ignore_patterns(jsonl_path):
221+
"""Build ``linkcheck_ignore`` patterns for known URIs.
222+
223+
Each URI is escaped and matched exactly so it cannot accidentally match
224+
part of another URL.
225+
"""
226+
return [
227+
rf"^{re.escape(uri)}$"
228+
for uri in set(_iter_uris_from_linkcheck_jsonl(jsonl_path))
229+
]
230+
231+
232+
# Only populated for PR and merge queue runs. Kept at module level so tests
233+
# can inspect it directly without reloading the module under different
234+
# environments.
235+
_linkcheck_historic_patterns = []
236+
if os.getenv("GITHUB_EVENT_NAME") in _LINKCHECK_PR_EVENT_NAMES:
237+
_linkcheck_historic_patterns = _historic_linkcheck_ignore_patterns(
238+
_BASE_LINKCHECK_OUTPUT
239+
)
240+
linkcheck_ignore.extend(_linkcheck_historic_patterns)
241+
187242
# -- Options for extlinks ----------------------------------------------------------
188243
# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration
189244

0 commit comments

Comments
 (0)