fix(ci): staleness gate fails on named defects, not on the calendar #1014
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
| # SPDX-License-Identifier: MPL-2.0 | |
| name: Documentation Format Enforcement | |
| on: | |
| push: | |
| branches: [main, master] | |
| pull_request: | |
| branches: [main, master] | |
| # Estate guardrail: cancel superseded runs so re-pushes / rebased PR | |
| # updates do not pile up queued runs against the shared account-wide | |
| # Actions concurrency pool. Applied only to read-only check workflows | |
| # (no publish/mutation), so cancelling a superseded run is always safe. | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| permissions: | |
| contents: read | |
| jobs: | |
| check-doc-format: | |
| timeout-minutes: 10 | |
| name: Check Documentation Format | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4 | |
| - name: Check for duplicate documentation formats | |
| run: | | |
| DUPLICATES=0 | |
| # .adoc-primary docs: keep only .adoc. README is NOT here — README is a | |
| # GitHub-required Markdown file (see the README rule below). | |
| for doc in ARCHITECTURE ROADMAP PHILOSOPHY INSTALL; do | |
| if [ -f "${doc}.md" ] && [ -f "${doc}.adoc" ]; then | |
| echo "::error::Duplicate documentation: ${doc}.md and ${doc}.adoc both exist. Keep only .adoc" | |
| DUPLICATES=$((DUPLICATES + 1)) | |
| fi | |
| done | |
| # README: AsciiDoc is canonical estate-wide (ADR-004). A README.md | |
| # alongside README.adoc is legitimate ONLY when it is a *derived* | |
| # artefact — it must carry the GENERATED banner and the repo must | |
| # declare a [publishing.readme] consumer in descriptiles. A hand- | |
| # maintained README.md next to README.adoc is the duplicate to remove | |
| # (this is the case the June 2026 runaway inverted). | |
| if [ -f "README.md" ] && [ -f "README.adoc" ]; then | |
| if grep -q "GENERATED from README.adoc" README.md 2>/dev/null; then | |
| echo "✓ README.md is a derived artefact (GENERATED banner present)" | |
| else | |
| echo "::error::README.md alongside README.adoc is not a derived artefact (no GENERATED banner). Under ADR-004, README.adoc is canonical; either derive README.md via readme-derive-reusable.yml (with a [publishing.readme] declaration) or remove the hand-maintained README.md." | |
| DUPLICATES=$((DUPLICATES + 1)) | |
| fi | |
| fi | |
| # CONTRIBUTING can have both but .md should just be a redirect | |
| if [ -f "CONTRIBUTING.md" ] && [ -f "CONTRIBUTING.adoc" ]; then | |
| if ! grep -q "See.*CONTRIBUTING.adoc" CONTRIBUTING.md 2>/dev/null; then | |
| echo "::warning::CONTRIBUTING.md exists alongside CONTRIBUTING.adoc but is not a redirect" | |
| fi | |
| fi | |
| if [ $DUPLICATES -gt 0 ]; then | |
| echo "::error::Found $DUPLICATES duplicate documentation files" | |
| exit 1 | |
| fi | |
| echo "✓ No duplicate documentation formats found" | |
| - name: Check documentation format | |
| run: | | |
| # ADR-004: README.adoc is canonical estate-wide. A lone README.adoc | |
| # is correct and needs no action — do NOT nudge it to Markdown. A | |
| # README.md is only produced by deriving it (readme-derive-reusable.yml) | |
| # for repos that declare a [publishing.readme] consumer. GitHub renders | |
| # .adoc natively; only external Markdown-only consumers (Glama, the | |
| # profile repo) need the derived .md. | |
| # Community-health files that GitHub special-cases by exact .md name: | |
| # SECURITY.md, CONTRIBUTING.md (can redirect), CODE_OF_CONDUCT.md, CHANGELOG.md | |
| # Check other docs are .adoc | |
| for doc in ARCHITECTURE ROADMAP PHILOSOPHY INSTALL; do | |
| if [ -f "${doc}.md" ]; then | |
| echo "::warning::${doc}.md should be ${doc}.adoc" | |
| fi | |
| done | |
| echo "✓ Documentation format check complete" | |
| - name: Verify GitHub-required files exist | |
| run: | | |
| # These files are required/preferred by GitHub in .md format | |
| MISSING=0 | |
| if [ ! -f "SECURITY.md" ]; then | |
| echo "::warning::SECURITY.md not found (required for GitHub security tab)" | |
| fi | |
| if [ ! -f "LICENSE.txt" ] && [ ! -f "LICENSE" ]; then | |
| echo "::warning::LICENSE file not found" | |
| fi | |
| echo "✓ GitHub-required files check complete" |