From 9e93f61cc0c6855c0eee9255b336506c464878fa Mon Sep 17 00:00:00 2001 From: Andrew Jong Date: Sat, 29 Aug 2026 18:59:58 -0400 Subject: [PATCH] =?UTF-8?q?hotfix(docs):=20rename=20the=20stable=20docs=20?= =?UTF-8?q?alias=20'latest'=20=E2=86=92=20'main';=20serialize=20gh-pages?= =?UTF-8?q?=20pushes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The site default and stable-docs alias is now /main/ (restores pre-0.20 bookmark URLs) instead of /latest/. Both deploy workflows point the 'main' alias at the current MAJOR.MINOR slug and set-default main; repo links and skill/microagent references updated. Also adds a shared concurrency group to the three docs deploy workflows: concurrent deploys raced on the gh-pages push (observed: develop deploy rejected with 'fetch first' while the main deploy pushed). VERSION 0.20.2 → 0.20.3 (CI/docs-only; bump required by the PR gate). Co-Authored-By: Claude Fable 5 --- .agents/skills/bump-version-and-release/SKILL.md | 6 +++--- .env | 2 +- .github/workflows/deploy_docs_from_develop.yaml | 6 ++++++ .github/workflows/deploy_docs_from_main.yaml | 10 ++++++++-- .github/workflows/deploy_docs_from_release.yaml | 10 ++++++++-- .github/workflows/scripts/docs_reorder_versions.py | 2 +- .openhands/microagents/repo.md | 2 +- README.md | 2 +- 8 files changed, 29 insertions(+), 11 deletions(-) diff --git a/.agents/skills/bump-version-and-release/SKILL.md b/.agents/skills/bump-version-and-release/SKILL.md index 6471c065d..58c214f40 100644 --- a/.agents/skills/bump-version-and-release/SKILL.md +++ b/.agents/skills/bump-version-and-release/SKILL.md @@ -75,7 +75,7 @@ Three workflows in `.github/workflows/` interact with `VERSION`: ### 3. `deploy_docs_from_release.yaml` — versioned docs - **Trigger:** GitHub `release` event with `types: [published]`. -- **Behavior:** publishes the docs under the release's **MAJOR.MINOR slug** (tag `0.21.0` → `/0.21/`) titled with the full tag, points the `latest` alias at it, and makes `latest` the site default. A later hotfix republishes the same slug in place (retitled to the new patch version), so URLs never break within a minor line. +- **Behavior:** publishes the docs under the release's **MAJOR.MINOR slug** (tag `0.21.0` → `/0.21/`) titled with the full tag, points the `main` alias at it, and makes `main` the site default. A later hotfix republishes the same slug in place (retitled to the new patch version), so URLs never break within a minor line. - Companion workflows publish `develop` (slug `develop`, titled ` (unstable)`, pinned to the top of the version selector) and `main` (same MAJOR.MINOR slug mechanism as releases, so docs hotfixes go live without a release). There is no separate `main` docs version. So the full release path is: bump `VERSION` → PR → merge to `main`/`develop` (retag unchanged images and/or rebuild changed ones + push + sign) → cut a GitHub Release matching that VERSION (versioned docs go live). @@ -253,8 +253,8 @@ For a true release (dropping the pre-release suffix): 3. [ ] In the same PR, retitle the Release Notes section to `## X.Y.Z — YYYY-MM-DD` and open a fresh `## (Unreleased)` above it. 4. [ ] Merge to `main`. 5. [ ] Wait for `docker-build.yml` to push and sign all images. -6. [ ] Create a GitHub Release with tag `X.Y.Z` (matching `VERSION` exactly). Publishing the release fires `deploy_docs_from_release.yaml`, which publishes the docs under the `X.Y` slug (titled `X.Y.Z`) and points the `latest` alias and site default at it. -7. [ ] Verify the docs site shows the new version under the version selector and that `latest` resolves to it. +6. [ ] Create a GitHub Release with tag `X.Y.Z` (matching `VERSION` exactly). Publishing the release fires `deploy_docs_from_release.yaml`, which publishes the docs under the `X.Y` slug (titled `X.Y.Z`) and points the `main` alias and site default at it. +7. [ ] Verify the docs site shows the new version under the version selector and that the `main` alias (site default) resolves to it. ## References diff --git a/.env b/.env index a3e991a5e..6fef3b39f 100644 --- a/.env +++ b/.env @@ -12,7 +12,7 @@ PROJECT_NAME="airstack" # If you've run ./airstack.sh setup, then this will auto-generate from the git commit hash every time a change is made # to a Dockerfile or docker-compose.yaml file. Otherwise this can also be set explicitly to make a release version. # auto-generated from git commit hash -VERSION="0.20.2" +VERSION="0.20.3" # Image-tag discriminator ONLY (appears in the image tag suffix, e.g. ..._robot-x86-64_dev). # No Dockerfile consumes it: "prebuilt" does NOT bake the built ros_ws into the image today — # a real prebuilt (workspace-baked) stage is future work. Keep "dev" (mounted code, built live). diff --git a/.github/workflows/deploy_docs_from_develop.yaml b/.github/workflows/deploy_docs_from_develop.yaml index 2b170424d..f312c9d1b 100644 --- a/.github/workflows/deploy_docs_from_develop.yaml +++ b/.github/workflows/deploy_docs_from_develop.yaml @@ -18,6 +18,12 @@ on: 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 diff --git a/.github/workflows/deploy_docs_from_main.yaml b/.github/workflows/deploy_docs_from_main.yaml index eea1f4d0b..5a973562d 100644 --- a/.github/workflows/deploy_docs_from_main.yaml +++ b/.github/workflows/deploy_docs_from_main.yaml @@ -10,6 +10,12 @@ on: - ".github/workflows/deploy_docs_from_main.yaml" branches: - main +# 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 jobs: @@ -65,8 +71,8 @@ jobs: VERSION=$(grep -m1 '^VERSION=' .env | cut -d= -f2- | tr -d '"') SLUG=$(echo "${VERSION}" | cut -d. -f1-2) echo "Deploying main's docs: slug ${SLUG}, title ${VERSION}" - mike deploy --push --update-aliases --title "${VERSION}" "${SLUG}" latest - mike set-default latest --push + mike deploy --push --update-aliases --title "${VERSION}" "${SLUG}" main + mike set-default main --push # 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. diff --git a/.github/workflows/deploy_docs_from_release.yaml b/.github/workflows/deploy_docs_from_release.yaml index c1c1adc34..c2a7ff15a 100644 --- a/.github/workflows/deploy_docs_from_release.yaml +++ b/.github/workflows/deploy_docs_from_release.yaml @@ -4,6 +4,12 @@ on: release: types: [published] +# 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 jobs: @@ -58,8 +64,8 @@ jobs: run: | SLUG=$(echo "${TAG}" | cut -d. -f1-2) echo "Deploying release docs: slug ${SLUG}, title ${TAG}" - mike deploy --push --update-aliases --title "${TAG}" "${SLUG}" latest - mike set-default latest --push + mike deploy --push --update-aliases --title "${TAG}" "${SLUG}" main + mike set-default main --push # 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. Guarded: the script may be absent on release tags diff --git a/.github/workflows/scripts/docs_reorder_versions.py b/.github/workflows/scripts/docs_reorder_versions.py index 77c02b75d..abf9142f7 100644 --- a/.github/workflows/scripts/docs_reorder_versions.py +++ b/.github/workflows/scripts/docs_reorder_versions.py @@ -4,7 +4,7 @@ mike re-sorts versions.json on every deploy, and the non-numeric "develop" version does not reliably sort above the MAJOR.MINOR release slugs. We want develop (which carries the higher, unreleased version -number) listed first, while the `latest` alias stays the set-default +number) listed first, while the `main` alias stays the set-default landing version. Every workflow that runs `mike deploy` must re-run this script afterwards, since any mike write restores mike's own ordering. diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 29fe29283..f8e126b24 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -82,7 +82,7 @@ AirStack/ - Uses AirLab Docker registry credentials **Documentation Deployment**: -- **Main Branch** (`deploy_docs_from_main.yaml`): Republishes the current MAJOR.MINOR docs slug (e.g. `/0.20/`) from pushes to `main` and points `latest` at it +- **Main Branch** (`deploy_docs_from_main.yaml`): Republishes the current MAJOR.MINOR docs slug (e.g. `/0.20/`) from pushes to `main` and points the `main` alias at it - **Develop Branch** (`deploy_docs_from_develop.yaml`): Deploys docs to develop version on pushes to `develop` - **Release** (`deploy_docs_from_release.yaml`): Deploys docs to versioned release on GitHub releases - Uses MkDocs Material with mike for versioning diff --git a/README.md b/README.md index 6ae482fbb..45835a804 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ git clone --recursive -j8 git@github.com:castacks/AirStack.git && cd AirStack airstack up --play --wait ``` -Then follow the [Getting Started guide](https://docs.theairlab.org/latest/docs/getting_started/) +Then follow the [Getting Started guide](https://docs.theairlab.org/main/docs/getting_started/) and the [Modular AirStack Walkthrough](docs/getting_started/modular_airstack.md). No Linux box or GPU? [Run AirStack on OSMO](docs/tutorials/airstack_on_osmo.md) from any laptop.