Repository navigation
ci: check Markdown links on every PR and fix all dead links - #1609
Conversation
The archived gaurav-nelson link-check action ran with check-modified-files-only and its default base-branch master, so every push to dev that touched a Markdown file checked all ~120 files that differ from master and failed on their stale links. get-diff-action already lists the files the push changed; the job now passes exactly those to markdown-link-check, and leaves book/ (links relative to the staged mdBook tree, checked by the docs build) out. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the
|
The check now covers only the files a change touches, so it runs on all pull requests again (it was disabled there while it diffed against master). Its config ignores iacr.org, whose Cloudflare front answers any non-browser client with a 403 challenge, and maps the docs-site path api/rpc/ to rpc/openapi/, the repository files prepare-docs.py publishes there. File names are passed after `--` so none is read as an option. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
✅ Final review complete — no blockers (commit 6e87dbd) · triage: normal |
A full markdown-link-check of the repository (book/ excepted) reported 29 dead links; it is clean now. - Moved or deleted pages point to their current location, a tagged permalink, or a Web Archive copy; a deleted Google Doc is named instead of linked. - Links to upstream Tendermint docs and to this repository's own files are relative where Tenderdash has the page (p2p spec, tools docs, confix, Dockerfile). - proto-doc links types from other packages in spec/abci/api.md to their proto directories (and google.protobuf types to protobuf.dev) instead of anchors the page does not have; api.md is regenerated. - The link check treats 504 as alive: GitHub answers bursts of checks with transient 504s. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
thepastaclaw
left a comment
There was a problem hiding this comment.
Final validation — Phase 1 + Phase 2
The workflow and documentation fixes are generally correct, and the available CI checks are green, including the Markdown link check. One blocking coverage gap remains: changed Markdown files inside dot-directories are silently omitted because the diff action does not enable minimatch dot matching; the new blanket IACR ignore is also an in-scope suggestion because it allows future mistyped IACR URLs to pass.
🔴 1 blocking | 🟡 1 suggestion(s)
Review provenance
Source: reviewer 1: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)
- Triage:
normalbygpt-6.1-sol(effort low) — The change is primarily documentation and CI tooling, but it modifies workflow execution, link-check configuration, generated documentation, and Makefile behavior across the repository, warranting more than a trivial or low-effort review without affecting a critical surface. - Phase 1 reviewers:
muse-spark-1.3-contributor— general (completed, effort xhigh); agentphase1-reviewer - Phase 1 model:
muse-spark-1.3-contributor— not quota-gated; passed overgemini-3.8-flash-high(antigravity quota lookup failed),glm-5.3-flash(not used above high effort; tier asks max) - Second Phase-2 pass: on this first full review every Phase-2 reviewer also ran a second, independent time, and the verifier weighed both sets
- Fresh verifier:
gpt-6.1-sol— final-verifier; agentsol-verifier - Phase 2 reviewers:
gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.
In `.github/workflows/markdown-links.yml`:
- [BLOCKING] .github/workflows/markdown-links.yml:32-35: Include Markdown files in dot-directories
The `**/**.md` pattern is evaluated without minimatch dot matching, so tracked Markdown files such as `.github/PULL_REQUEST_TEMPLATE.md`, `.github/copilot-instructions.md`, and `.agents/skills/tenderdash-release/SKILL.md` are not selected when they are changed. A pull request touching only one of these files therefore produces an empty file list and exits successfully without checking its links. This also differs from the branch-creation path, which enumerates tracked Markdown files directly. Enable dot matching so that `book/**` remains the only deliberate exclusion.
In `.md-link-check.json`:
- [SUGGESTION] .md-link-check.json:6-11: Avoid a blanket ignore for IACR URLs
The domain-wide ignore exempts every `eprint.iacr.org` and `www.iacr.org` URL, not just the three currently cited papers that return Cloudflare challenges. As a result, a future typo in an IACR URL, such as an incorrect paper number, will pass the link check and conflicts with this PR's goal of detecting dead links in changed Markdown. Archived copies are available for the three existing RFC references, so those links can be changed to archive URLs and the blanket ignore removed.
get-diff-action matches PATTERNS with minimatch, which skips dot paths by default, so changes to .github/*.md or .agents/**/*.md were never checked. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
thepastaclaw
left a comment
There was a problem hiding this comment.
Re-review — Final validation — Phase 1 + Phase 2
The current implementation correctly restores pull-request coverage, includes Markdown files in dot-directories, excludes the staged mdBook sources, and applies the generated documentation link rewrites consistently. CI reports success for the build, tests, lint, documentation, and Markdown-link checks; only review and PR Hygiene checks remain pending. One in-scope suggestion remains regarding the breadth of the IACR URL exemption.
🟡 1 suggestion(s)
Approved: nothing here blocks the merge. The non-blocking findings are optional: fix them forward, in this PR or a follow-up, without waiting for another review round.
Still open from earlier rounds (1)
- 🟡 Suggestion: Avoid a blanket ignore for IACR URLs —
.md-link-check.json:6-11(thread)
Review provenance
Source: reviewer 1: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)
- Triage:
normalbygpt-6.1-sol(effort low) — The pull request makes a cross-cutting CI workflow and link-check configuration change, including script behavior, dependency usage, path handling, and generated documentation updates, so it warrants ordinary review despite not touching critical runtime code. - Phase 1 reviewers:
muse-spark-1.3-contributor— general (completed, effort xhigh); agentphase1-reviewer - Phase 1 model:
muse-spark-1.3-contributor— not quota-gated; passed overgemini-3.8-flash-high(antigravity quota lookup failed),glm-5.3-flash(not used above high effort; tier asks max) - Fresh final gate: an independent Phase-2 review ran after iterative findings were reconciled
- Fresh verifier:
gpt-6.1-sol— final-verifier; agentsol-verifier - Phase 2 reviewers:
gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.
In `.md-link-check.json`:
- [SUGGESTION] .md-link-check.json:6-11: Avoid a blanket ignore for IACR URLs
(carried; thread: https://github.com/dashpay/tenderdash/pull/1609#discussion_r4524843220)
|
Ready for review — |
|
Policy satisfied — this can merge. |
TL;DR: Fixes every dead link in the repository's Markdown, and makes the link check run on every pull request, only on the files a change touches, without false alarms.
User story
As a contributor or maintainer, I want broken links in the Markdown files I change reported on my pull request, without noise from files I did not touch or links that work.
Scenario
Base flow
A PR that edits any Markdown file is merged into
dev, and the "Check Markdown links" workflow runs on the push.Actual behavior
The job checks about 120 Markdown files, every file that differs from
master, and fails on hundreds of old or unreachable links. The files the merge actually changed are buried among them. For example, run 42693029742 for #1602 changed onlyCHANGELOG.md, whose links were all fine, and still failed with 350 dead links. Every push todevthat touches a Markdown file has failed this way since 2026-11-05.Expected behavior
On every pull request and on pushes to
dev/master, the job checks only the Markdown files that were added or changed, and fails only when one of them has a dead link.Detailed discussion
What was done
gaurav-nelson/github-action-markdown-link-check@v1(archived) ran withcheck-modified-files-only: yesand its defaultbase-branch: master, so ondevit diffed againstmaster.get-diff-action's file list only decided whether the step ran.markdown-link-check@3.14.2(the version the maintainedtcortaction installs) directly on the files fromget-diff-action(FORMAT: json, read withjq). The existing.md-link-check.jsonconfig is kept. A branch-creation push (GIT_DIFF=all) checks every tracked Markdown file.book/**is excluded:book/SUMMARY.mdandbook/README.mdlink relative to the staged mdBook tree, which produced 155 falseStatus: 400reports.prepare-docs.pyand the mdBook build in the docs workflow already check them.pull_requesttrigger is back, for every PR (it was disabled in build(github): fix broken github actions and regenerate some code #615 while the check diffed againstmaster), with the same concurrency and read-only permissions as the Markdown linter. A PR without Markdown changes passes at once..md-link-check.json: ignoreseprint.iacr.org/www.iacr.org, which answer every non-browser client with a Cloudflare 403 challenge (cf-mitigated: challenge). Rewrites…/api/rpc/to…/rpc/openapi/:prepare-docs.pypublishesrpc/openapi/asapi/rpc/on the docs site, so these links resolve to the file they will show, and a missing target is still reported.--, so a PR file name cannot be read as an option.book/excepted) is fixed: moved pages point to their current location or a tagged permalink, deleted ones to a Web Archive copy, and a deleted Google Doc is named instead of linked. Links to upstream Tendermint docs and to this repository's own files are relative where Tenderdash has the page (p2p spec, tools docs,internal/libs/confix,DOCKER/Dockerfile), as the docs site at https://dashpay.github.io/tenderdash/ is built from them.make proto-doclinks types from other packages in the generatedspec/abci/api.mdto their proto directories (andgoogle.protobuftypes to protobuf.dev) instead of anchors the page lacks;api.mdis regenerated with it.Testing
The step script was run locally:
[]→ "No changed Markdown files.", exit 0;["CHANGELOG.md","README.md"]→ exit 0;["docs/rfc/rfc-012-custom-indexing.md"]→ reports its dead link, exit 1;all→ 187 tracked files, none underbook/;the four files linking
api/rpc/index.htmlfailed before the config change and pass after it; a link to a missingapi/rpc/missing.htmlis still reported;a file citing iacr.org passes.
a full check of all 187 tracked Markdown files outside
book/passes (29 dead links before).markdownlint reports no new findings in the edited files. This PR also runs the workflow through its new
pull_requesttrigger on the 20 Markdown files it changes.actionlintreports only that it does not know the existingubuntu-26.04runner label.Breaking changes
None. A PR that edits a file with an old dead link now gets a red, non-required check until that link is fixed.
Prior work
dev, where diffing againstmastercovers the whole development line.Attribution
🤖 Generated with Claude Code
🤖 Co-authored by Claudius the Magnificent AI Agent
PR Hygiene ·
6e87dbdgithub(.github/workflows/markdown-links.yml) — approved by lklimek.md-link-check.json,DOCKER/README.md,Makefileand 18 more) — approved by lklimekWhen every merge requirement is met, the
PR Hygienecheck passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.