From 628d4804fc67d3a63026cc7b5acecfa68717cd65 Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Fri, 21 Aug 2026 21:24:46 +0200 Subject: [PATCH] Docs deploy skips pre-releases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `release: published` fires for pre-releases too — `released` is the type that skips them — so a `v0.5.0rc1` release would have run `mike deploy --update-aliases latest` and `mike set-default`, serving rc docs as the site default. That is the opposite of the workflow's own rule that the site tracks the released CLI: PyPI hands an rc only to someone who asks for it by name, so the site must keep serving the last full release. One `if` on the deploy job. `github.event.release` is null on a workflow_dispatch run, so the manual redeploy path stays unconditional. `pypi-publish.yaml` is deliberately untouched: PyPI derives "pre-release" from the PEP 440 version alone — an rc tag gives hatch-vcs `0.5.0rc1`, which `pip install` skips without `--pre` — never from the GitHub checkbox. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01AujePdgpiCcNnEJ99ruLFu --- .github/workflows/docs-deploy.yml | 15 ++++++++++----- CLAUDE.md | 2 +- docs/contributing/setup.md | 3 ++- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index f650808..e531ffb 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -9,11 +9,13 @@ name: Deploy Docs # # The site tracks the *released* CLI, not main: deploys happen on the # same trigger as the PyPI publish, so the docs never document behavior -# that `pip install lightcone-cli` can't deliver yet. For an -# intermediate deploy (typo fix, clarification), trigger manually from -# the Actions tab — workflow_dispatch runs against the selected ref and -# redeploys the snapshot for the given version (defaults to the latest -# tag reachable from that ref). +# that `pip install lightcone-cli` can't deliver yet. Pre-releases are +# skipped for the same reason — PyPI hands an rc only to someone who +# asks for it by name, so the site must keep serving the last full +# release. For an intermediate deploy (typo fix, clarification), +# trigger manually from the Actions tab — workflow_dispatch runs +# against the selected ref and redeploys the snapshot for the given +# version (defaults to the latest tag reachable from that ref). on: release: @@ -37,6 +39,9 @@ concurrency: jobs: deploy: + # A pre-release deploys nothing. `github.event.release` is null on a + # workflow_dispatch run, so the manual path stays unconditional. + if: ${{ !github.event.release.prerelease }} runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/CLAUDE.md b/CLAUDE.md index 246ff4b..ae5035d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -199,7 +199,7 @@ tests/ # pytest — mirrors src/ The whole docs site is versioned with [mike](https://github.com/squidfunk/mike) — specifically squidfunk's fork, which Zensical's versioning provider depends on. Each release deploys a full copy of the site to a subdirectory of the `gh-pages` branch (`/0.0.9/`, `/latest/`, etc.). Mike is enabled via `[project.extra.version] provider = "mike"` in `zensical.toml`; the version dropdown in the header is rendered natively. -Release flow: `.github/workflows/docs-deploy.yml` runs on every published release — it runs `mike deploy --push --update-aliases X.Y.Z latest` (version taken from the tag) followed by `mike set-default --push latest`, so the bare site root always redirects to `/latest/`. For an intermediate redeploy of an existing version, trigger the workflow manually from the Actions tab. For local/manual operations, run the same mike commands directly (`uv run mike list`, `uv run mike deploy ...`, `uv run mike delete ...` — the docs dependency group installs mike). +Release flow: `.github/workflows/docs-deploy.yml` runs on every published release — it runs `mike deploy --push --update-aliases X.Y.Z latest` (version taken from the tag) followed by `mike set-default --push latest`, so the bare site root always redirects to `/latest/`. A **pre-release deploys nothing**: `release: published` fires for pre-releases too (`released` is the type that skips them), and moving `latest` onto an rc would serve as default what `pip install` deliberately withholds, so the job carries `if: ${{ !github.event.release.prerelease }}`. PyPI needs no equivalent — "pre-release" there is derived from the PEP 440 version alone (an rc tag ⇒ hatch-vcs ⇒ `0.5.0rc1`), never from the GitHub checkbox, so `pypi-publish.yaml` stays unconditional. For an intermediate redeploy of an existing version, trigger the workflow manually from the Actions tab. For local/manual operations, run the same mike commands directly (`uv run mike list`, `uv run mike deploy ...`, `uv run mike delete ...` — the docs dependency group installs mike). Hosting: mike pushes to `gh-pages`. GitHub Pages (which serves docs.lightconeresearch.org) must be configured to "Deploy from a branch" / `gh-pages` in the repo's Pages settings, not via the Actions artifact deploy. Without this, `mike deploy` runs successfully but the site doesn't pick up versioned URLs in production. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index c234896..188f1cc 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -54,7 +54,8 @@ uv run zensical serve # live preview ``` The site deploys on release (`docs-deploy.yml`), so docs track the -released CLI, not `main`. +released CLI, not `main`. A pre-release deploys nothing — the site keeps +serving the last full release. ## Building the wheel