spec: 010 Task 11.2 — the trailing newline on the last 14 files #149
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
| name: docs | |
| on: | |
| push: | |
| pull_request: | |
| # Daily, for the `versions` job below. The event that invalidates a pinned | |
| # version is a release in *another* repository, so a push/PR-only trigger | |
| # would leave a stale pin undetected until someone happened to touch the | |
| # docs. See spec/009-getting_started_tutorials/design.md § D9. | |
| schedule: | |
| - cron: '17 6 * * *' | |
| jobs: | |
| check: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| # pagelint.py --changed derives its strict ranges from the merge-base, | |
| # so the full history has to be here. Present from the first version of | |
| # this file rather than added alongside that step, because a shallow | |
| # clone fails in a way that looks like "no changes" rather than an error. | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| - run: python3 tools/linkcheck.py | |
| # Repo-wide: banner, heading uniqueness, terminology and language tags are | |
| # errors on every page. Language tags joined that list with spec 011 Task | |
| # 7.2, which tagged the last 34 untagged fences — a rule with no remaining | |
| # debt needs no softer level. The using-directive debt does still have one, | |
| # so it stays a counted warning here and the backlog is visible without | |
| # blocking unrelated work. | |
| - run: python3 tools/pagelint.py | |
| # On a pull request the code rules become errors, but only for blocks that | |
| # overlap the diff. Fixing a typo on a 700-line page therefore obliges | |
| # nothing beyond the typo. | |
| # | |
| # This step must not pass vacuously. pagelint.py exits 2 — not 0 — when it | |
| # cannot resolve the ref or read the diff, so an unusable history fails the | |
| # build rather than reporting "no changed ranges". `fetch-depth: 0` above is | |
| # what makes origin/<base_ref> resolvable. | |
| # | |
| # It also cannot pass *silently* vacuously: spec 010 P2-3, the run opens by | |
| # printing how many files, hunks, pages and code blocks it examined, and | |
| # says so in as many words when the diff reaches no block. That last figure | |
| # is the one to read — the strict rules are per code block, so a diff of a | |
| # hundred prose files makes them strict about nothing. The description | |
| # sweep is the case in point: 149 files and 192 hunks, 5 blocks strict. | |
| # | |
| # base_ref goes through env rather than straight into the command line. | |
| # Git ref names may contain `;`, `&` and `$`, so a `${{ }}` expansion | |
| # inside `run:` is a shell-injection shape even when the value is a | |
| # branch name in this repository. | |
| - if: github.event_name == 'pull_request' | |
| env: | |
| BASE_REF: ${{ github.base_ref }} | |
| run: python3 tools/pagelint.py --changed "origin/$BASE_REF" | |
| # Spec 010 D3/D7, Q10's answer. Both read only the repository, so neither can | |
| # make the build flaky. `--verify` is deliberately NOT here: it fetches the live | |
| # sitemap, and a check whose failure mode is "the site was slow" teaches people | |
| # to ignore red builds. | |
| # | |
| # --check-shape asserts design §4's S1/S2/S3 — at least 2 pages per section, at | |
| # most 12 top-level entries, at most 4 URL segments — plus that no SUMMARY.md | |
| # heading carries leading whitespace. It was red on the 19-section tree this | |
| # spec replaced (6 singleton sections, 2 sections over 12 entries, and the | |
| # leading space at SUMMARY.md:154), which is how it proved it was not vacuous. | |
| # | |
| # --check-redirects asserts every redirect value resolves to a file that | |
| # exists, every key is a path that no longer publishes, and every byte of | |
| # .gitbook.yaml is printable ASCII. That last one is not a style rule: two | |
| # U+200B zero-width spaces in this repo's `structure:` key meant GitBook never | |
| # read that block, silently, for months — and they came from GitBook's own | |
| # published example, which still carries them. | |
| # | |
| # These gate rather than being run once at merge, because a redirect block that | |
| # is complete at merge and incomplete three PRs later is the same silent | |
| # failure in slow motion. | |
| - run: python3 tools/urlmap.py --check-shape | |
| - run: python3 tools/urlmap.py --check-redirects | |
| # Spec 009 D9 adds tools/versioncheck.py, which diffs the versions pinned in | |
| # tutorial prose against the latest non-prerelease on NuGet. The job is shaped | |
| # now so landing D9 is one file, not a workflow restructure. | |
| # | |
| # REMOVE THE GUARD when 009 D9 lands — it exists only to keep the build green | |
| # while the tool is absent, and inheriting it would silently un-gate the check. | |
| # The bare invocation is deliberate: versioncheck.py exits 2 when it cannot | |
| # reach NuGet, and an unreachable authority is an unchecked pin, not a pass. | |
| versions: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| - run: | | |
| if [ -f tools/versioncheck.py ]; then | |
| python3 tools/versioncheck.py | |
| else | |
| echo "tools/versioncheck.py not present yet (spec 009 D9) - skipping." | |
| fi |