ci: keep gh-pages small to avoid bloating clones (#365)

## Why

The `gh-pages` branch had grown to **811 commits / ~147 MB packed**
because every docs deploy (`mike deploy dev` on each merge, a version
dir per release, per-PR previews) commits a full copy of the built site
and nothing ever reclaims that history. A default `git clone` pulls
**all** branches, so every contributor was downloading ~150 MB even
though only `main` (~11 MB) is needed for development.

The history has already been purged out-of-band (gh-pages rebuilt as a
single orphan commit; full pre-purge site archived to the
[`docs-archive-2026-07-10`](https://github.com/QuEraComputing/bloqade/releases/tag/docs-archive-2026-07-10)
release). **Fresh clone dropped ~152 MB → ~29 MB.** This PR adds the
guards so it doesn't creep back.

## What

- **`.github/workflows/squash-gh-pages.yml`** (new) — monthly +
`workflow_dispatch` job that collapses `gh-pages` to a single orphan
commit. Safe: the branch is a generated artifact and every version is
rebuildable from its release tag.
- **`.github/workflows/pub_doc.yml`** — after each release deploy, prune
the live site to `dev` + the newest **3** releases (`KEEP_RELEASES`).
Older versions remain rebuildable from tags and archived in the release
asset.
- **`.github/scripts/select_old_doc_versions.py`** (new) — small,
unit-tested stdin→stdout filter that picks which versions to delete
(handles semver ordering, e.g. `v0.10.0` > `v0.9.0`).
- **Shared `gh-pages-write` concurrency group** across the dev deploy,
release deploy, and squash job so concurrent pushes can't clobber the
branch. `cancel-in-progress: false` (cancelling a mike push mid-flight
could corrupt gh-pages).

## Notes / follow-ups

- `cancel-in-progress` on the dev-docs deploy changes from `true` →
`false`: rapid merges to `main` now queue sequential dev deploys instead
of cancelling the older one. The monthly squash reclaims the extra
commits.
- The pr-preview workflow (`doc.yml`) is intentionally left out of the
shared lock to preserve its per-PR cancel behaviour; it already races
mike deploys today (pre-existing) and the monthly squash runs at a quiet
time (03:00 UTC on the 1st).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Roger-luo

.github/scripts/select_old_doc_versions.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Select stale mike doc versions to prune from the live site.
+
+Reads `mike list -j` JSON on stdin and prints, one per line, the release
+versions that should be deleted so that only the newest ``KEEP_RELEASES``
+releases remain live (``dev`` and any non-release entries are always kept).
+
+Older versions stay rebuildable from their git release tags and are captured
+in the ``docs-archive-*`` GitHub release asset, so pruning them from the
+deployed site loses nothing permanent.
+"""
+
+import json
+import os
+import re
+import sys
+
+RELEASE_RE = re.compile(r"^v?\d+\.\d+")
+
+
+def is_release(version: str) -> bool:
+    return RELEASE_RE.match(version) is not None
+
+
+def sem_key(version: str):
+    return [int(n) for n in re.findall(r"\d+", version)]
+
+
+def main() -> int:
+    keep = int(os.environ.get("KEEP_RELEASES", "3"))
+    entries = json.load(sys.stdin)
+    releases = sorted(
+        (e["version"] for e in entries if is_release(e["version"])),
+        key=sem_key,
+        reverse=True,
+    )
+    for version in releases[keep:]:
+        print(version)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/workflows/devdoc.yml

@@ -4,9 +4,12 @@ on:
     branches:
       - main
 
+# Serialize with every other workflow that writes to gh-pages (release deploy,
+# history squash) so concurrent pushes can't clobber the branch. Queued dev
+# deploys run in order rather than cancelling an in-flight gh-pages push.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
+  group: gh-pages-write
+  cancel-in-progress: false
 
 jobs:
   documentation:

.github/workflows/pub_doc.yml

@@ -4,9 +4,13 @@ on:
     tags:
       - "v*"
 
+# Serialize with every other workflow that writes to gh-pages (dev deploy,
+# release deploy, history squash) so concurrent pushes can't clobber the branch.
+# cancel-in-progress must stay false here: cancelling a mike push mid-flight
+# could leave gh-pages in a broken state.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
+  group: gh-pages-write
+  cancel-in-progress: false
 
 jobs:
   documentation:
@@ -55,3 +59,18 @@ jobs:
         run: |
           git fetch origin gh-pages --depth=1
           uv run mike deploy --update-alias --push ${TAG_VERSION} latest
+      # Keep the live site small: retain only `dev` plus the newest N release
+      # versions. Older versions stay rebuildable from their release tags and
+      # are captured in the `docs-archive-*` release asset.
+      - name: Prune old versions from the live site
+        env:
+          KEEP_RELEASES: "3"
+        run: |
+          git fetch origin gh-pages --depth=1
+          to_delete=$(uv run mike list -j | python3 .github/scripts/select_old_doc_versions.py)
+          if [ -n "$to_delete" ]; then
+            echo "Deleting old versions: $to_delete"
+            uv run mike delete --push $to_delete
+          else
+            echo "Nothing to prune."
+          fi

.github/workflows/squash-gh-pages.yml

@@ -0,0 +1,49 @@
+# Keeps the gh-pages branch from re-accumulating build history.
+#
+# Every docs deploy (mike / pr-preview) adds a full commit to gh-pages, so its
+# history grows without bound even though only the tip is ever served. This job
+# periodically collapses gh-pages to a single orphan commit. The content is a
+# generated artifact and every version is rebuildable from its release tag, so
+# discarding the history is always safe.
+name: Compact gh-pages history
+
+on:
+  schedule:
+    # 03:00 UTC on the 1st of each month (a quiet time, to avoid racing deploys)
+    - cron: "0 3 1 * *"
+  workflow_dispatch: {}
+
+# Share a lock with the workflows that write to gh-pages so a squash never
+# races a mike/pr-preview push.
+concurrency:
+  group: gh-pages-write
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  squash:
+    name: Squash gh-pages to a single commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: gh-pages
+          fetch-depth: 0
+
+      - name: Collapse history into one orphan commit
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          before=$(git rev-list --count HEAD)
+          if [ "$before" -le 1 ]; then
+            echo "gh-pages already has $before commit(s); nothing to squash."
+            exit 0
+          fi
+          git checkout --orphan _squash
+          git add -A
+          git commit -q -m "docs: compact gh-pages (squash $before commits)"
+          git branch -M _squash gh-pages
+          git push --force origin gh-pages
+          echo "Squashed gh-pages from $before commits to 1."