ci: enforce example-docs sync and mirror 4-phase workflow - #46
Merged
Conversation
Add scripts/check_docs_sync.py, wired as the 'Docs sync gate' CI job, to prevent recurrence of the drift fixed in #42: - BLOCKING: every example directory must be referenced in README.md. - WARNING: examples without an expected/ golden file or tests/ suite are flagged (non-blocking) so the coverage backlog can be paid down; intentional exceptions live in scripts/docs-sync-allowlist.txt. Mirror the 4-phase workflow (previously only in AGENTS.md) into CONTRIBUTING.md and add explicit 'tests updated' and 'docs updated' checkboxes to the PR template, so human contributors see the same code+tests+docs-together rule. Closes #44
Harden find_untested() so a file named expected or tests cannot be mistaken for a coverage directory (Oracle review follow-up).
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.
Summary
Adds enforcement so implementation, tests, and docs stay in sync — the governance gap identified in #44. Prevents recurrence of the drift fixed in #42.
Changes
scripts/check_docs_sync.py(new) — wired as the Docs sync gate CI job:quickstart/,migration/,templates/,performance/,fundamentals/) must be referenced inREADME.md.expected/golden file ortests/suite are flagged so the coverage backlog can be paid down incrementally.scripts/docs-sync-allowlist.txt(new) — coverage-warning exceptions with recorded reasons (the three non-deterministicperformance/benchmarks).CONTRIBUTING.md— mirrors the 4-phase workflow (previously only inAGENTS.md, invisible to human contributors) and documents the gate..github/pull_request_template.md— adds explicit tests updated and docs updated checkboxes.Verification
python3 scripts/check_docs_sync.py→ exit 0 (all 26 examples documented; 11 coverage warnings, non-blocking).python3 -m doctest scripts/check_docs_sync.py→ passes.ruff check/ruff format --checkon the script → clean.ci.ymlparses as valid YAML.Closes #44