fix(scripts): repoint checks at the .adoc files that exist - #59
Conversation
The .md -> .adoc documentation migration moved these files but never updated
the scripts that READ them, so every check naming a .md has been operating on
a file that no longer exists.
Repointed: CHANGELOG.md->CHANGELOG.adoc CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc CONTRIBUTING.md->CONTRIBUTING.adoc MAINTAINERS.md->MAINTAINERS.adoc QUICKSTART.md->QUICKSTART.adoc SECURITY.md->SECURITY.adoc
Three failure modes were in play across the estate, all fixed by the same
change:
* hard fail - 'check "X.md exists" "[ -f X.md ]"' can never pass
* wrong score - '[ -f X.md ] && ((doc_score++))' silently scores lower
* SILENT SKIP - 'if [ -f X.md ]; then ...greps... fi' skips the whole block,
so the checks inside never run and the gate reports success
by not checking at all
Human-readable labels are repointed too, so failure messages name the file that
is actually inspected. Where a script did 'git add ... X.md', that is fixed as
well - it would have failed at release time.
Only tokens whose .adoc twin exists in this repository were rewritten; anything
without a twin was left untouched for separate triage.
Found by an estate-wide sweep of 454 repos: 56 such checks across 18 repos.
Same defect class as hyperpolymath/Axiom.jl#82.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📜 Recent review details⏰ Context from checks skipped due to timeout. (1)
🔇 Additional comments (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe verification script now checks AsciiDoc documentation files for required files and policy content. Markdown references were replaced for security, contribution, conduct, maintainer, changelog, TPCF, emotional-safety, and quickstart checks. ChangesAsciiDoc verification
Estimated code review effort: 1 (Trivial) | ~5 minutes Merge Risk: ⚪ Minimal · up to This localized script update repoints checks to the existing documentation files, with no actionable merge-blocking risk remaining after normal checks and review. Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1 files. ✨ Finishing Touches📝 Generate docstrings
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Up to standards ✅🟢 Issues
|
There was a problem hiding this comment.
Pull Request Overview
This PR updates the rsr-verify.sh script to target AsciiDoc (.adoc) files instead of Markdown (.md) files, ensuring compliance checks for existence and content validation remain functional after the documentation migration. While the change aligns with the migration intent, there is a mismatch between the PR description and the provided code: the description mentions updating git add commands, but the diff for rsr-verify.sh contains no such logic. Additionally, there are no accompanying tests or coverage data to verify that the script correctly handles the new file extensions and their contents.
About this PR
- The PR description explicitly states that 'Where a script did git add … X.md, that is fixed as well', but the provided diff for 'rsr-verify.sh' does not contain any git commands. This suggests either a missing file in the PR or a mismatch between the description and the implementation.
- There are no test updates or coverage data provided to verify that the script changes work as intended in an environment with .adoc files.
Test suggestions
- Verify rsr-verify.sh successfully passes existence checks when .adoc files are present.\n- [ ] Verify grep-based content checks correctly identify required strings within .adoc files.\n- [ ] Verify the script fails/warns as expected when a required .adoc file is missing or lacks mandatory content.
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Verify rsr-verify.sh successfully passes existence checks when .adoc files are present.\n- [ ] Verify grep-based content checks correctly identify required strings within .adoc files.\n- [ ] Verify the script fails/warns as expected when a required .adoc file is missing or lacks mandatory content.
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
The
.md→.adocdocumentation migration moved these files but never updated the scripts that read them, so every check naming a.mdhas been operating on a file that no longer exists.Repointed: CHANGELOG.md->CHANGELOG.adoc CODE_OF_CONDUCT.md->CODE_OF_CONDUCT.adoc CONTRIBUTING.md->CONTRIBUTING.adoc MAINTAINERS.md->MAINTAINERS.adoc QUICKSTART.md->QUICKSTART.adoc SECURITY.md->SECURITY.adoc
Three failure modes were in play across the estate, all fixed by the same change:
check "X.md exists" "[ -f X.md ]"[ -f X.md ] && ((doc_score++))if [ -f X.md ]; then …greps… fiLabels are repointed too, so failure messages name the file actually inspected. Where a script did
git add … X.md, that is fixed as well — it would have failed at release time.Only tokens whose
.adoctwin exists here were rewritten; anything without a twin was left for separate triage.Found by an estate-wide sweep of 454 repos: 56 such checks across 18 repos. Same class as hyperpolymath/Axiom.jl#82.