Skip to content

fix(docs-gate): accept root CONTRIBUTING.adoc — 94% of failures were false positives #850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 1 commit into from
Sep 18, 2026
Merged

fix(docs-gate): accept root CONTRIBUTING.adoc — 94% of failures were false positives #850

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions scripts/check-docs-presence.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,14 @@
# default; GitHub-required community-health files stay Markdown):
# README.adoc | README.md
# LICENSE | LICENSE.txt | LICENSE.md
# CONTRIBUTING.md | 3-practice/CONTRIBUTING.adoc
# CONTRIBUTING.md | CONTRIBUTING.adoc | 3-practice/CONTRIBUTING.adoc
#
# CONTRIBUTING.adoc at the repo root is accepted because the estate policy named
# above makes AsciiDoc the default, and it is what the estate actually uses:
# sampling 40 repos on 2026-09-18 found 32 carrying a root CONTRIBUTING.adoc and
# no CONTRIBUTING.md, versus 2 genuinely missing the document. Without it this
# gate failed 94% of the repos it reported as non-compliant, the day the
# CONTRIBUTING cutoff armed.
#
# Usage: check-docs-presence.sh [repo-root]
#
Expand Down Expand Up @@ -83,7 +90,7 @@ grace_missing=""
have README.adoc README.md || blocking_missing="$blocking_missing README"
have LICENSE LICENSE.txt LICENSE.md || blocking_missing="$blocking_missing LICENSE"

if ! have CONTRIBUTING.md 3-practice/CONTRIBUTING.adoc; then
if ! have CONTRIBUTING.md CONTRIBUTING.adoc 3-practice/CONTRIBUTING.adoc; then
# String comparison is sound here: YYYY-MM-DD sorts chronologically, and both
# operands are format-validated above.
if [[ "$TODAY" < "$ENFORCE_CONTRIBUTING_FROM" ]]; then
Expand Down
14 changes: 14 additions & 0 deletions scripts/tests/governance-gates-505-test.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,20 @@
assert "alternate extensions accepted" 0 "✅ Core documentation present" \
env DOCS_TODAY="$AFTER" "$DOCS" "$r"

# Regression: AsciiDoc is the estate default and a root CONTRIBUTING.adoc is the
# dominant real-world layout (32 of 34 sampled non-compliant repos). This used to
# fail, so the gate reported 94% false positives once the cutoff armed on
# 2026-08-21. The "alternate extensions" case above did not catch it because it
# only ever placed CONTRIBUTING.adoc under 3-practice/.
r=$(mkrepo docs-adoc-root README.adoc LICENSE CONTRIBUTING.adoc)
assert "root CONTRIBUTING.adoc accepted (regression: 94% false positives)" 0 \
"✅ Core documentation present" \

Check warning on line 79 in scripts/tests/governance-gates-505-test.sh

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Define a constant instead of using the literal '✅ Core documentation present' 4 times. 


See more on https://sonarcloud.io/project/issues?id=hyperpolymath_standards&issues=AaC01fZjraTRlD8Rb_oR&open=AaC01fZjraTRlD8Rb_oR&pullRequest=850
env DOCS_TODAY="$AFTER" "$DOCS" "$r"
# ...and it must still be the grace-windowed document, not an unconditional pass.
assert "root CONTRIBUTING.adoc still warns pre-cutoff only when ABSENT" 0 \
"NOT YET ENFORCED" \
env DOCS_TODAY="$BEFORE" "$DOCS" "$(mkrepo docs-adoc-root-absent README.adoc LICENSE)"

# README/LICENSE are BLOCKING NOW — the grace window must not shelter them.
r=$(mkrepo docs-no-readme LICENSE CONTRIBUTING.md)
assert "missing README fails even pre-cutoff" 1 "Missing required documentation: README" \
Expand Down
Loading