Repository navigation
ci: improve linkcheck job behavior and failure modes - #2182
Open
rgommers wants to merge 3 commits into
Open
rgommers wants to merge 3 commits into
rgommers wants to merge 3 commits into
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Compare PR and merge-queue links with the exact base revision's Sphinx JSONL report. Escape and anchor known URLs so new paths and fragments remain checked, while preserving checks for local links and manual exclusions. Restore an exact-SHA baseline cache published only by main pushes. On a cache miss, fetch the base commit and generate its report in a temporary worktree rather than weakening enforcement. Accept existing broken links in that report, but reject missing or malformed reports. Make new-link failures block PRs and merge queues. Keep full checks on pushes informational and retain failing daily checks for site-wide link monitoring. Upload full reports and summarize failing URLs so maintainers can investigate outages without blocking unrelated changes.
Add a Nox test session to CI and use pytest fixtures and parametrization to cover exact URL matching, report validation, and monitoring summaries. Exercise Sphinx against a local HTTP server to prove existing broken URLs are skipped while new working and broken URLs are actually checked. Use temporary Git repositories to verify cache reuse, environment isolation, and worktree cleanup on success and failure. Include a shallow clone so fetching a missing base commit is tested as it occurs in CI. Keep network requests local and Git mutations confined to disposable repositories so contributors can run the suite against their own checkout.
Explain how to run full local linkcheck and the pytest suite through Nox, including report locations and the use of temporary repositories in tests. Describe exact-base filtering and cache-miss generation for PRs and merge queues. Distinguish informational full checks after main pushes from failing daily monitoring, and point contributors to uploaded reports and job summaries when investigating link failures.
This was referenced Nov 11, 2026
aidaiprivate-source
approved these changes
Nov 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Reviewers
1 more reviewerAt least 1 approving review is required to merge this pull request.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses the persistent issues with linkcheck failures on unrelated PRs. Closes gh-2037.
The key choice to make is when linkcheck fails and where that shows up. This PR does the following (aligned with the high-level approach mentioned in gh-2037):
The baseline is an exact base commit, without fallback to older cached reports. URL matching is exact, so new paths, query strings, and fragments remain checked. A cache miss generates the baseline in a temporary worktree; existing broken links are accepted when the base run produces a valid report.
Because this stuff is inherently quite fragile, introduce a small test suite that validates that broken links, a missing cache, and the report generation are actually working as advertised. This introduces pytest as a new test dependency; that should be fine (I considered unittest, but there's no reason to avoid a pytest dependency in this repo).
Finally, the last commit adds notes on linkcheck to the contributor guide.
Developed with Codex / Sol 6.1. Tested all CI modes on my fork at rgommers#1.
📚 Documentation preview 📚: https://python-packaging-user-guide--2182.org.readthedocs.build/en/2182/