Bump VERSION to 0.21.0-dev.5 after sync from main #67
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: Build/Publish Develop Docs | |
| on: | |
| push: | |
| paths: | |
| - "docs/**" | |
| - "mkdocs.yml" | |
| - "*.md" | |
| - "stacks/**" | |
| - "tools/gen_docs_catalog.py" | |
| - ".github/workflows/deploy_docs_from_develop.yaml" | |
| branches: | |
| - develop | |
| # Module-docs freshness (RFC #379 §9): the catalog is regenerated from the | |
| # live registry on every deploy, so a registry change only reaches the site | |
| # when a deploy runs. Until registry-driven repository_dispatch lands | |
| # ("within a day, exact at releases"), a weekly rebuild plus manual dispatch | |
| # keeps the develop catalog from going stale. | |
| workflow_dispatch: | |
| schedule: | |
| - cron: "17 6 * * 1" # weekly, Mondays 06:17 UTC | |
| # Serialize gh-pages pushes: concurrent docs deploys race on the branch | |
| # push (observed: develop deploy rejected with 'fetch first' when the main | |
| # deploy pushed at the same time). | |
| concurrency: | |
| group: docs-deploy-gh-pages | |
| cancel-in-progress: false | |
| permissions: | |
| contents: write | |
| issues: write # drift alarm files an issue when the committed catalog lags the registry | |
| jobs: | |
| deploy: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| # schedule/workflow_dispatch run on the default branch; this | |
| # workflow always publishes the develop docs. | |
| ref: develop | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@v4 | |
| with: | |
| python-version: 3.10.6 | |
| - name: Install Dependencies | |
| run: | | |
| pip install mkdocs-material mkdocs-same-dir mkdocs-redirects pyyaml | |
| pip install pillow cairosvg mike | |
| # DRIFT ALARM: the committed docs/modules pages + the fixture index | |
| # (tests/meta/fixtures/modules_index/) must mirror the LIVE registry. | |
| # A merged trunk PR with an unmerged registry PR — or vice versa — | |
| # otherwise publishes a catalog that silently disagrees with git | |
| # (this happened with `mighty`, 2026-08-29). Develop deploy only: | |
| # main/release committed pages intentionally lag develop. NEVER fails | |
| # the deploy (the regeneration below publishes the current catalog | |
| # regardless); it just makes the mismatch loud — a warning annotation, | |
| # a job summary, and at most one open issue. The sync-modules-index | |
| # workflow opens the PR that clears it. | |
| - name: Catalog drift alarm (committed pages vs live registry) | |
| env: | |
| GH_TOKEN: ${{ github.token }} | |
| run: | | |
| rm -rf .modules-index-drift | |
| git clone --depth 1 https://github.com/castacks/airstack-modules-index .modules-index-drift \ | |
| || { echo "skipped: registry unreachable — no drift verdict"; exit 0; } | |
| mkdir -p /tmp/no-fetched-modules | |
| if python3 tools/gen_docs_catalog.py --index .modules-index-drift \ | |
| --modules-dir /tmp/no-fetched-modules --check 2> drift.txt; then | |
| echo "committed catalog is in sync with the live registry" | |
| exit 0 | |
| fi | |
| echo "::warning title=Module catalog drift::committed docs/modules + fixture disagree with the live registry. The published catalog is regenerated and current; trunk needs a sync PR — run the sync-modules-index workflow." | |
| { echo "## Module catalog drift"; echo; echo '```'; head -c 5000 drift.txt; echo '```'; } >> "$GITHUB_STEP_SUMMARY" | |
| if [ -z "$(gh issue list --label docs-catalog-drift --state open --json number --jq '.[].number')" ]; then | |
| gh label create docs-catalog-drift --color D93F0B \ | |
| --description "Committed module catalog disagrees with the live registry" 2>/dev/null || true | |
| gh issue create --title "Module catalog drift: committed docs/modules disagrees with the live registry" \ | |
| --label docs-catalog-drift \ | |
| --body "$(printf 'Detected by the develop docs deploy: %s/%s/actions/runs/%s\n\nThe committed docs/modules pages + tests/meta/fixtures/modules_index/ do not match regeneration from the live airstack-modules-index (usually a registry PR merged without its trunk sync, or the reverse). The published develop catalog is regenerated live and stays correct; git is what lags.\n\nFix: run the **sync-modules-index** workflow (Actions tab) and merge its PR — or sync manually per the extract-module skill registration step.\n\n```\n%s\n```' "$GITHUB_SERVER_URL" "$GITHUB_REPOSITORY" "$GITHUB_RUN_ID" "$(head -c 5000 drift.txt)")" | |
| else | |
| echo "drift issue already open — not filing a duplicate" | |
| fi | |
| # RFC #379 §9: module docs ride the docs deploy. Shallow-clone the | |
| # registry index and each REGISTERED module repo at its registered_ref | |
| # into the gitignored modules/ dir, then regenerate docs/modules/ so | |
| # the published catalog is fresh even when the committed pages lag. | |
| # FAILURE ISOLATION: nothing in this step may fail the deploy — an | |
| # unreachable registry or module repo degrades to the committed pages / | |
| # a stub note on the module's page. | |
| - name: Fetch registry index and registered module repos | |
| run: | | |
| rm -rf .modules-index modules | |
| git clone --depth 1 https://github.com/castacks/airstack-modules-index .modules-index \ | |
| || echo "skipped: registry index unreachable (committed catalog pages will be served)" | |
| if [ -d .modules-index/modules ]; then | |
| mkdir -p modules | |
| python3 tools/gen_docs_catalog.py --index .modules-index --list-refs | | |
| while IFS=$'\t' read -r name repo ref; do | |
| ( git init -q "modules/$name" \ | |
| && git -C "modules/$name" remote add origin "$repo" \ | |
| && git -C "modules/$name" fetch -q --depth 1 origin "$ref" \ | |
| && git -C "modules/$name" checkout -q FETCH_HEAD ) \ | |
| || { rm -rf "modules/$name"; echo "skipped: module $name ($repo @ $ref) unreachable — its page keeps the stub note"; } | |
| done | |
| python3 tools/gen_docs_catalog.py --index .modules-index --modules-dir modules \ | |
| || echo "skipped: catalog regeneration failed (committed pages will be served)" | |
| fi | |
| - name: Setup Docs Deploy | |
| run: | | |
| git config --global user.name "Docs Deploy" | |
| git config --global user.email "docs.deploy@example.co.uk" | |
| - name: Build Docs Website | |
| run: | | |
| VERSION=$(grep -m1 '^VERSION=' .env | cut -d= -f2- | tr -d '"') | |
| mike deploy --push --title "${VERSION} (unstable)" develop | |
| # mike re-sorts versions.json on every deploy, so pin develop — the | |
| # higher, unreleased version — back to the top of the version selector | |
| # after each deploy. | |
| - name: Reorder version selector (develop first) | |
| run: | | |
| git worktree add ../ghp-reorder gh-pages | |
| python3 .github/workflows/scripts/docs_reorder_versions.py ../ghp-reorder/versions.json | |
| if ! git -C ../ghp-reorder diff --quiet -- versions.json; then | |
| git -C ../ghp-reorder commit -m "Reorder version selector: develop above main" versions.json | |
| git push origin gh-pages | |
| fi | |
| git worktree remove ../ghp-reorder |