From d8c19943376813496cf5c76a3aa64232692a02db Mon Sep 17 00:00:00 2001 From: MarTrepodi Date: Sun, 18 Oct 2026 09:26:16 -0400 Subject: [PATCH] ci(release): dispatch the docs deploy on the staged release branch prepare-release.yml pushes release/vX.Y.Z with GITHUB_TOKEN, and GitHub does not start workflows from GITHUB_TOKEN pushes, so docs.yml's `push: release/**` trigger never fired for a staged release. Dispatch docs.yml on the new branch right after pushing it (workflow_dispatch is the documented exception), which needs `actions: write`. CONTRIBUTING: drop the manual "run Deploy docs" step, add the github-pages environment's gh-pages deployment branch to the cutover (branch-based Pages builds still deploy through that environment, so it must not be deleted), and record that the cutover is done. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docs.yml | 5 +++-- .github/workflows/prepare-release.yml | 16 ++++++++++++++++ CONTRIBUTING.md | 10 ++++++---- 3 files changed, 25 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 400f892..5631519 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,7 +22,7 @@ name: Deploy docs # build-checks every PR. # # Pushes made with GITHUB_TOKEN (such as prepare-release.yml's) do not start this -# workflow; run it by hand on that release branch instead. +# workflow, so prepare-release.yml dispatches it on the branch it stages. # # One-time setup: Settings -> Pages -> Build and deployment -> Source: # "Deploy from a branch", branch `gh-pages`, folder `/ (root)`. @@ -40,7 +40,8 @@ on: - "uv.lock" - ".github/workflows/docs.yml" - ".github/scripts/docs_version.py" - # Run by hand on a release/* branch, e.g. after prepare-release.yml pushed it. + # Dispatched by prepare-release.yml for the branch it stages; also run by hand + # on a release/* branch to rebuild that version. # Runs started on any other ref are skipped by the job condition below. workflow_dispatch: diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml index 8935480..6ff794e 100644 --- a/.github/workflows/prepare-release.yml +++ b/.github/workflows/prepare-release.yml @@ -26,6 +26,8 @@ permissions: # Read merged PRs and their issues to restate closing keywords (closing_issues.py). pull-requests: read issues: read + # Dispatch docs.yml on the release branch (see "Deploy the release docs"). + actions: write jobs: prepare: @@ -127,6 +129,20 @@ jobs: git commit -m "chore(changelog): update for ${tag}" git push --force-with-lease origin "${branch}" + # A push made with GITHUB_TOKEN does not start workflows, so docs.yml's + # `push: release/**` trigger never fires for the branch staged above. + # workflow_dispatch is the documented exception, so start the deploy + # explicitly: the release's docs publish (and take `latest` if it is the + # newest stable) as soon as its branch exists. + - name: Deploy the release docs + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + branch="release/${{ steps.version.outputs.tag }}" + gh workflow run docs.yml --repo "${{ github.repository }}" --ref "${branch}" + echo "Dispatched docs.yml on ${branch}." + - name: Summarise how to open the release PR run: | set -euo pipefail diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b72b1b4..9bc51f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -547,7 +547,7 @@ Never paste your comlink `access_key` / `secret_key` into an issue. Releases are handled by the maintainer through GitHub Actions. Contributors don't need to manage versioning or releases, but here's how it works for reference: -1. **prepare release** (`prepare-release.yml`) is dispatched on `develop`. It computes the next version from the Conventional Commits since the last tag (or a chosen `patch`/`minor`/`major` bump), regenerates `CHANGELOG.md`, and pushes a `release/vX.Y.Z` branch. If the computed version is a major, the job summary lists the commit lines that triggered it, and an `auto` bump stops unless one is a real `BREAKING CHANGE:` footer (see [Commit Messages](#commit-messages)). +1. **prepare release** (`prepare-release.yml`) is dispatched on `develop`. It computes the next version from the Conventional Commits since the last tag (or a chosen `patch`/`minor`/`major` bump), regenerates `CHANGELOG.md`, pushes a `release/vX.Y.Z` branch, and dispatches **Deploy docs** on it. If the computed version is a major, the job summary lists the commit lines that triggered it, and an `auto` bump stops unless one is a real `BREAKING CHANGE:` footer (see [Commit Messages](#commit-messages)). 2. The maintainer opens the release PR from that branch into `main` (a link is in the workflow summary). Its body restates every `Closes #N` from the PRs merged since the last release, so GitHub closes those issues when it merges. CI runs as normal and the PR is merged. 3. **comlink-python release** (`release.yml`) is dispatched on `main`. It reads the version from `CHANGELOG.md`, builds the package — [hatch-vcs](https://github.com/ofek/hatch-vcs) stamps that version, so **no version string is committed to the repo** — and publishes to [PyPI](https://pypi.org/project/swgoh-comlink/) via trusted publishing. 4. Only after a successful publish is the Git tag created and a GitHub Release cut, with release notes auto-generated from the PR history. @@ -583,7 +583,7 @@ Deploys run **only from `release/*` branches of `swgoh-utils/comlink-python`**. - **Pre-releases** take the alias for their kind (`alpha`, `beta`, `rc`, or `dev`, which wins for `aN.devM`) only when they are at least as new as every deployed version of that kind. They never touch `latest` or the default, and every page shows a "pre-release" banner ([`overrides/main.html`](overrides/main.html); the deploy sets `DOCS_PRERELEASE`, which feeds `extra.prerelease` in `mkdocs.yml`). Stable versions instead get Material's "older version" banner whenever they are not `latest`. - **Every release is its own folder.** `2.5.0` and `2.5.1` both stay in the picker; remove ones you no longer want with `mike delete` (below). - **Nothing else deploys.** Pushes to `main`, `develop` or tags, runs in forks, and manual runs on a non-`release/*` ref skip the job. Deleting a release branch after its PR merges leaves its docs on `gh-pages`. -- **Release timing.** `prepare-release.yml` pushes `release/vX.Y.Z` before the release PR merges and before the PyPI publish, so a stable release's docs can go live (and take `latest`) before the package is on PyPI. That push is made with `GITHUB_TOKEN`, though, and GitHub does not start workflows from `GITHUB_TOKEN` pushes: run **Actions → Deploy docs → Run workflow** on the new release branch (later pushes to the branch, such as review fixes, deploy on their own). +- **Release timing.** `prepare-release.yml` pushes `release/vX.Y.Z` before the release PR merges and before the PyPI publish, so a stable release's docs can go live (and take `latest`) before the package is on PyPI. That push is made with `GITHUB_TOKEN`, and GitHub does not start workflows from `GITHUB_TOKEN` pushes, so `prepare-release.yml` dispatches **Deploy docs** on the new branch itself (`workflow_dispatch` is the documented exception). Later pushes to the branch, such as review fixes, deploy on their own. - Deploys queue in the `gh-pages` concurrency group, so they never race. **Preview the versioned site locally** without touching the remote (the deploy commits to a local `gh-pages` branch only): @@ -612,9 +612,11 @@ The site used to be deployed by `actions/deploy-pages` from `main`, as a single uv run mike set-default --push latest ``` -3. **Switch the Pages source.** In **Settings → Pages → Build and deployment**, change **Source** from "GitHub Actions" to **"Deploy from a branch"**, branch **`gh-pages`**, folder **`/ (root)`**. Check that the root URL opens the 2.5.0 docs. +3. **Switch the Pages source.** First allow the branch to deploy: in **Settings → Environments → `github-pages` → Deployment branches and tags**, add **`gh-pages`** (branch-based Pages builds still deploy through this environment, and it only allowed `main`). Then, in **Settings → Pages → Build and deployment**, change **Source** from "GitHub Actions" to **"Deploy from a branch"**, branch **`gh-pages`**, folder **`/ (root)`**. Check that the root URL opens the 2.5.0 docs. 4. **Protect `gh-pages`** (optional, recommended). Add a ruleset or branch protection rule for `gh-pages` that blocks force pushes and deletion. Leave direct pushes allowed for GitHub Actions: the deploy pushes with the workflow's `GITHUB_TOKEN`, so a rule that requires pull requests or status checks would block it (or add "GitHub Actions" to the bypass list). -5. **Clean up.** The old `github-pages` environment created by `deploy-pages` can be deleted, or kept for history. +5. **Keep the `github-pages` environment.** Branch-based Pages builds (`pages-build-deployment`) deploy through it, so deleting it or removing `gh-pages` from its deployment branches stops the site from updating. + +This cutover was completed on 2026-10-18: `2.5.0` (`latest`) and `3.0.0a2` (`alpha`) are published, and `gh-pages` is protected by the **Protect gh-pages** ruleset. #### Maintaining versions