diff --git a/.agents/skills/bump-version-and-release/SKILL.md b/.agents/skills/bump-version-and-release/SKILL.md index 58c214f40..674c53a53 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 `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. +- **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 sets the site default (root redirect) to the pinned slug — so landed-on/copied URLs stay valid across future releases. 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 `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. +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 the site default (root redirect, pinned to the slug) at it. +7. [ ] Verify the docs site shows the new version under the version selector, that the root URL redirects to the new `X.Y` slug, and that the `main` alias resolves to it. ## References diff --git a/.env b/.env index 6fef3b39f..5667faebf 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.3" +VERSION="0.20.4" # 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_main.yaml b/.github/workflows/deploy_docs_from_main.yaml index 5a973562d..232d75285 100644 --- a/.github/workflows/deploy_docs_from_main.yaml +++ b/.github/workflows/deploy_docs_from_main.yaml @@ -72,7 +72,10 @@ jobs: SLUG=$(echo "${VERSION}" | cut -d. -f1-2) echo "Deploying main's docs: slug ${SLUG}, title ${VERSION}" mike deploy --push --update-aliases --title "${VERSION}" "${SLUG}" main - mike set-default main --push + # Root URL redirects to the PINNED slug (not the moving alias): URLs + # people land on and copy stay valid across future releases. /main/ + # remains as a moving alias for deep links. + mike set-default "${SLUG}" --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 c2a7ff15a..d6a726fc8 100644 --- a/.github/workflows/deploy_docs_from_release.yaml +++ b/.github/workflows/deploy_docs_from_release.yaml @@ -65,7 +65,10 @@ jobs: SLUG=$(echo "${TAG}" | cut -d. -f1-2) echo "Deploying release docs: slug ${SLUG}, title ${TAG}" mike deploy --push --update-aliases --title "${TAG}" "${SLUG}" main - mike set-default main --push + # Root URL redirects to the PINNED slug (not the moving alias): URLs + # people land on and copy stay valid across future releases. /main/ + # remains as a moving alias for deep links. + mike set-default "${SLUG}" --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 abf9142f7..a79dfdc63 100644 --- a/.github/workflows/scripts/docs_reorder_versions.py +++ b/.github/workflows/scripts/docs_reorder_versions.py @@ -4,8 +4,8 @@ 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 `main` alias stays the set-default -landing version. Every workflow that runs `mike deploy` must re-run +number) listed first, while the site default (root redirect) points at +the current MAJOR.MINOR release slug. 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 f8e126b24..5c6014a40 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 the `main` alias at it +- **Main Branch** (`deploy_docs_from_main.yaml`): Republishes the current MAJOR.MINOR docs slug (e.g. `/0.20/`) from pushes to `main`, points the `main` alias at it, and pins the site root redirect to the slug - **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