docs: lint the same files CI does, then make CI keep them level - #32
Merged
Conversation
CONTRIBUTING told contributors to run shellcheck locally "because it runs in CI, so running it here saves a round trip", then listed five files where CI lints six. tests/check-links.sh was missing. A contributor could follow the documented steps exactly, see a silent shellcheck, push, and fail the lint job on a file they were never told to check. A doc that is wrong about how to pass CI is worse than no doc, because it is trusted. Correcting the list alone would leave the two free to drift apart again, which is the same shape as the false install-path claim that was fixed in README and left standing in ROADMAP for weeks. So both lists are now read from the file that owns them and compared as sets, and neither can be updated alone. A third assertion checks that every listed file exists. Two lists that agree with each other but no longer match the repo is the failure a set comparison structurally cannot catch, so it needs its own check. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
CONTRIBUTING.mdsays to run shellcheck locally "because it runs in CI, so running them locally saves a round trip", then lists five files.ci.yml:21lints six.So a contributor could follow the documented steps exactly, see a silent shellcheck, push, and fail the lint job on a file they were never told to check. A doc that is wrong about how to pass CI is worse than no doc, because it is the one people trust.
Why this is not a one-line fix
Correcting the list alone leaves the two free to drift apart again. That is the same shape as the false "installs as a plugin in one step" claim, which was corrected in
README.mdand left standing inROADMAP.mdfor weeks because the fix was scoped to the file where someone noticed it.CONTRIBUTING.md:51names that incident as the reason to fix the claim rather than the file.So both lists are now read from the file that owns them and compared as sets. Neither can be updated alone.
A third assertion checks that every listed file exists. Two lists that agree with each other but no longer match the repo is precisely the failure a set comparison structurally cannot catch, so it needs its own check. This mirrors the reasoning already recorded at
tests/run.sh:1290.Verification
296/296pass, shellcheck clean on all six files.Mutation-tested per
CONTRIBUTING.md:82("A test that cannot fail is not a test"):CONTRIBUTING lints the same files CI doesred, reportingonly in CI: tests/check-links.shevery file in the shellcheck list existsred, reportingmissing: tests/gone.shThe second row is the one worth noting: it goes red while the parity check stays green, which is the point of having both.
🤖 Generated with Claude Code