Problem
The link checker workflow (.github/workflows/docs.yml) runs on every PR that touches a .md or .html file and is causing more friction than value.
The failures seen in practice fall into three categories:
- GitHub 5xx transient errors - GitHub's CDN occasionally returns 502/500 to unauthenticated bots. The workflow doesn't pass a GitHub token to lychee, so GitHub URLs (which make up the majority of links in this repo) are inherently unreliable to check this way.
- Pre-existing broken URLs - e.g.
github.com/hi/issues/scoring in CHANGELOG.md, a malformed URL that has been there unnoticed. The checker didn't prevent it from merging; it just flags it on every subsequent PR.
- Transient network errors - general flakiness from checking hundreds of external URLs in CI.
The result is a check that fails regularly for reasons unrelated to what the PR author changed, which erodes trust in CI.
Options considered
Weekly scheduled run with issue creation - lychee supports --output and you can pipe results into gh issue create. But this still requires someone to triage broken changelog links and transient GitHub errors on a weekly cadence, which probably isn't worth the effort.
Pass a GitHub token to lychee - would fix the GitHub-specific flakiness but not the general transient error problem, and still leaves the maintenance burden.
Remove the workflow entirely - the links that matter (README, active docs) are unlikely to rot without someone noticing organically. If a link breaks badly enough to matter, someone files a bug.
Recommendation
Remove the workflow. The maintenance overhead of keeping it green exceeds the value it delivers for this repo.
Opened by Claude Code under the supervision of Bill Murdock.
Problem
The link checker workflow (
.github/workflows/docs.yml) runs on every PR that touches a.mdor.htmlfile and is causing more friction than value.The failures seen in practice fall into three categories:
github.com/hi/issues/scoringinCHANGELOG.md, a malformed URL that has been there unnoticed. The checker didn't prevent it from merging; it just flags it on every subsequent PR.The result is a check that fails regularly for reasons unrelated to what the PR author changed, which erodes trust in CI.
Options considered
Weekly scheduled run with issue creation - lychee supports
--outputand you can pipe results intogh issue create. But this still requires someone to triage broken changelog links and transient GitHub errors on a weekly cadence, which probably isn't worth the effort.Pass a GitHub token to lychee - would fix the GitHub-specific flakiness but not the general transient error problem, and still leaves the maintenance burden.
Remove the workflow entirely - the links that matter (README, active docs) are unlikely to rot without someone noticing organically. If a link breaks badly enough to matter, someone files a bug.
Recommendation
Remove the workflow. The maintenance overhead of keeping it green exceeds the value it delivers for this repo.
Opened by Claude Code under the supervision of Bill Murdock.