chore(ci): trunk-based CI + one-button release

.github/actions/download-frontend-artifact/action.yml

@@ -8,9 +8,13 @@ description: >-
 
 inputs:
   branch:
-    description: Branch whose latest successful frontend build to fetch (main or develop).
+    # Always `main`, including for release builds: this action needs a *previously successful*
+    # run on the branch, and `release` only ever gets the commit that is already on `main`.
+    # Sourcing from `release` would fetch the previous release's SPA, or nothing at all on the
+    # first one.
+    description: Branch whose latest successful frontend build to fetch.
     required: false
-    default: develop
+    default: main
 
 runs:
   using: composite

.github/release.yml

@@ -0,0 +1,36 @@
+# Categorises the notes GitHub generates for a release (`--generate-notes` in
+# .github/workflows/github-release.yml).
+#
+# NOTE: GitHub categorises by PR **label**, not by PR-title prefix. The `feat:` / `fix:` /
+# `docs:` / `chore:` title convention in extralit/docs/community/contributor.md is for humans
+# and stays unenforced — to make a PR land under a heading below, give it the matching label.
+# Anything unlabelled still shows up, under "Other changes".
+changelog:
+  exclude:
+    authors:
+      # Exact logins — GitHub matches these verbatim, so the `[bot]` suffix is required.
+      - dependabot[bot]
+      - github-actions[bot]
+  categories:
+    - title: ✨ Features
+      labels:
+        - enhancement
+        - feature
+    - title: 🐛 Fixes
+      labels:
+        - bug
+        - fix
+    - title: 📚 Documentation
+      labels:
+        - documentation
+    - title: 🧹 Maintenance
+      labels:
+        - refactor
+        - refactoring
+        - infrastructure
+        - deployment
+        - chore
+    # Catch-all. Must stay last — GitHub assigns each PR to the first matching category.
+    - title: Other changes
+      labels:
+        - "*"

.github/workflows/extralit-frontend.build-push-dev.yml

@@ -6,7 +6,7 @@ name: Deploy PR preview HF Space
 # Deliberately decoupled from extralit-server.yml so it does NOT run on every push:
 #   - auto:   only when a PR (touching the server or frontend) is marked "ready for review"
 #   - manual: workflow_dispatch with a PR number, to (re)deploy a preview on demand
-# main/develop deploys keep flowing through extralit-server.yml as before.
+# main/release deploys keep flowing through extralit-server.yml as before.
 
 on:
   # Note: `ready_for_review` only fires on a draft→ready transition. A PR opened
@@ -66,11 +66,9 @@ jobs:
 
       # No pytest here — preview-only path. The live frontend preview for this PR is published to
       # Vercel by extralit-frontend.yml; the HF Space only needs a bundled fallback UI, so bake
-      # the prebuilt develop frontend artifact instead of rebuilding from source.
+      # the prebuilt frontend artifact from `main` instead of rebuilding from source.
       - name: Download prebuilt frontend statics
         uses: ./.github/actions/download-frontend-artifact
-        with:
-          branch: develop
 
       - name: Build package
         run: |
@@ -102,7 +100,7 @@ jobs:
     secrets: inherit
 
   # Opportunistic: this PR has its own ephemeral HF Space (extralit-dev/pr-<n>), so point the
-  # PR's Vercel preview at it instead of the shared develop backend. Vercel's native Git
+  # PR's Vercel preview at it instead of the shared dev backend. Vercel's native Git
   # integration builds the preview; we just set a branch-scoped Preview env var (read by
   # extralit-frontend/vercel.ts at build time) and redeploy the branch's latest preview so it
   # takes effect now. Best-effort — never blocks the preview pipeline.

.github/workflows/extralit-frontend.yml

@@ -10,9 +10,12 @@ on:
   push:
     branches:
       - main
-      - develop
-      - feat/**
-      - releases/**
+      - release
+    paths:
+      - "extralit-frontend/**"
+      - ".github/workflows/extralit-frontend.yml"
+
+  pull_request:
     paths:
       - "extralit-frontend/**"
       - ".github/workflows/extralit-frontend.yml"

.github/workflows/extralit-server.build-docker-images.yml

@@ -32,9 +32,8 @@ jobs:
 
       - name: Read package info
         id: package-info
-        working-directory: extralit-server
         run: |
-          PACKAGE_VERSION=$(grep '__version__' src/extralit_server/_version.py | cut -d'"' -f2)
+          PACKAGE_VERSION=$(python3 scripts/bump_version.py check)
           PACKAGE_NAME="extralit-server"
           echo "PACKAGE_NAME=$PACKAGE_NAME" >> $GITHUB_OUTPUT
           echo "PACKAGE_VERSION=$PACKAGE_VERSION" >> $GITHUB_OUTPUT

.github/workflows/extralit-server.yml

@@ -1,7 +1,9 @@
 name: Build Extralit server package
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.sha }}
+  # Keyed on the ref, not the sha: a release pushes `main`, `release` and the tag at the same
+  # commit, so a sha-keyed group would make those runs cancel each other at random.
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 on:
@@ -10,9 +12,13 @@ on:
   push:
     branches:
       - main
-      - develop
-      - feat/**
-      - releases/**
+      - release
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+    paths:
+      - "extralit-server/**"
+
+  pull_request:
     paths:
       - "extralit-server/**"
 
@@ -22,7 +28,6 @@ permissions:
 jobs:
   build:
     name: Build `extralit-server` package
-    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
 
     defaults:
@@ -128,11 +133,9 @@ jobs:
 
       # The server no longer builds the frontend from source. The live UI is published to Vercel
       # by extralit-frontend.yml; here we just bake a prebuilt SPA into the wheel as the bundled
-      # fallback UI (main for release builds, else develop).
+      # fallback UI. Always sourced from `main` (see the action for why).
       - name: Download prebuilt frontend statics
         uses: ./.github/actions/download-frontend-artifact
-        with:
-          branch: ${{ github.ref_name == 'main' && 'main' || 'develop' }}
 
       - name: Build package
         run: |
@@ -152,28 +155,26 @@ jobs:
   build_docker_images:
     name: Build docker images
     uses: ./.github/workflows/extralit-server.build-docker-images.yml
-    if: |
-      github.ref == 'refs/heads/main'
-      || github.ref == 'refs/heads/develop'
-      || contains(github.ref, 'releases/')
-      || github.event_name == 'workflow_dispatch'
-      || (github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork && !github.event.pull_request.draft)
+    # Branch pushes (`main`, `release`) and manual dispatch only. PRs get tests here and nothing
+    # else — their preview images are built by extralit-frontend.build-push-dev.yml on
+    # `ready_for_review`. Tags only publish to PyPI; the image was already built from `release`.
+    if: github.ref_type == 'branch' && github.event_name != 'pull_request'
     needs:
       - build
     with:
-      is_release: ${{ github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch' }}
-      publish_latest: ${{ github.ref == 'refs/heads/main' }}
+      is_release: ${{ github.ref_name == 'release' }}
+      publish_latest: ${{ github.ref_name == 'release' }}
     secrets: inherit
 
   # This job will publish extralit-server python package into PyPI repository
   publish_release:
     name: Publish Release
     runs-on: ubuntu-latest
-    if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch' }}
+    # Tags are the only thing that publishes. release.yml creates them; never push one by hand.
+    if: startsWith(github.ref, 'refs/tags/v')
 
     needs:
       - build
-      - build_docker_images
 
     defaults:
       run:
@@ -203,7 +204,7 @@ jobs:
 
       - name: Read package info
         run: |
-          PACKAGE_VERSION=$(grep '__version__' src/extralit_server/_version.py | cut -d'"' -f2)
+          PACKAGE_VERSION=$(python3 "$GITHUB_WORKSPACE/scripts/bump_version.py" check)
           PACKAGE_NAME="extralit-server"
           echo "PACKAGE_VERSION=$PACKAGE_VERSION" >> $GITHUB_ENV
           echo "PACKAGE_NAME=$PACKAGE_NAME" >> $GITHUB_ENV
@@ -220,6 +221,5 @@ jobs:
           pip install --index-url https://test.pypi.org/simple --no-deps  $PACKAGE_NAME==$PACKAGE_VERSION
 
       - name: Publish Package to PyPI 🥩
-        if: github.ref == 'refs/heads/main'
         run: |
           uv publish --token ${{ secrets.AR_PYPI_API_TOKEN }} dist/*

.github/workflows/extralit.docs.yml

@@ -12,7 +12,6 @@ on:
       - "v[0-9]+.[0-9]+.[0-9]+"
     branches:
       - "main"
-      - "develop"
       - "docs/**"
     paths:
       - ".github/workflows/extralit.docs.yml"
@@ -63,25 +62,35 @@ jobs:
           git config --global user.email "${{ github.actor }}@users.noreply.github.com"
 
       - name: Print GitHub ref info
-        run: echo "${{ github.ref }}"
-          echo "${{ github.head_ref }}"
+        env:
+          REF: ${{ github.ref }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: echo "ref=$REF head_ref=$HEAD_REF"
 
+      # Trunk is the bleeding edge, so `main` is what you get by default; `stable` is moved by
+      # the tag step below. (Before the trunk-based migration this was inverted: `main` was
+      # `stable` and `develop` was `latest`.)
       - name: Deploy Extralit docs (branch /main)
-        run: |
-          uv run mike deploy stable --push
-        if: github.ref == 'refs/heads/main'
-
-      - name: Deploy Extralit docs (branch /develop)
         run: |
           uv run mike deploy latest --push
           uv run mike set-default --push latest
-        if: github.ref == 'refs/heads/develop' || github.event_name == 'workflow_dispatch'
+        if: github.ref == 'refs/heads/main'
 
       - name: Deploy Extralit docs (release $version)
         run: |
           version=$(echo $TAG_VERSION | awk -F \. {'print $1"."$2'})
           echo "Deploying version ${version}"
-          uv run mike deploy $version --push
+          # One-time migration, then a permanent no-op: the pre-trunk workflow published `stable`
+          # as its own *version* (a duplicate copy of the docs). mike refuses an alias whose name
+          # collides with a version, and --update-aliases only re-points names that are already
+          # aliases — so without this the first tagged release fails outright. Once `stable` is an
+          # alias it no longer appears as a version and this matches nothing.
+          if uv run mike list --json | jq -e '.[] | select(.version == "stable")' > /dev/null; then
+            echo "Retiring the legacy 'stable' version so it can become an alias"
+            uv run mike delete stable --push
+          fi
+          # `stable` as an alias of vX.Y, --update-aliases so it moves off the previous release.
+          uv run mike deploy "$version" stable --update-aliases --push
         if: startsWith(github.ref, 'refs/tags/')
         env:
           TAG_VERSION: ${{ github.ref_name }}

.github/workflows/extralit.yml

@@ -1,7 +1,9 @@
 name: Build Extralit Package & Publish
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.sha }}
+  # Keyed on the ref, not the sha: a release pushes `main`, `release` and the tag at the same
+  # commit, so a sha-keyed group would make those runs cancel each other at random.
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 on:
@@ -10,9 +12,15 @@ on:
   push:
     branches:
       - main
-      - develop
-      - feat/**
-      - releases/**
+      - release
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+    paths:
+      - "extralit/**"
+      - "!extralit/docs/**"
+      - "!extralit/mkdocs.yml"
+
+  pull_request:
     paths:
       - "extralit/**"
       - "!extralit/docs/**"
@@ -24,7 +32,6 @@ permissions:
 
 jobs:
   build:
-    if: github.event.pull_request.draft == false
     services:
       extralit-container:
         image: extralitdev/extralit-hf-space:latest
@@ -133,7 +140,8 @@ jobs:
   publish_release:
     name: Publish Release
     runs-on: ubuntu-latest
-    if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch' }}
+    # Tags are the only thing that publishes. release.yml creates them; never push one by hand.
+    if: startsWith(github.ref, 'refs/tags/v')
 
     permissions:
       # This permission is needed for private repositories.
@@ -167,7 +175,7 @@ jobs:
 
       - name: Read package info
         run: |
-          PACKAGE_VERSION=$(grep '__version__' src/extralit/_version.py | cut -d'"' -f2)
+          PACKAGE_VERSION=$(python3 "$GITHUB_WORKSPACE/scripts/bump_version.py" check)
           PACKAGE_NAME="extralit"
           echo "PACKAGE_VERSION=$PACKAGE_VERSION" >> $GITHUB_ENV
           echo "PACKAGE_NAME=$PACKAGE_NAME" >> $GITHUB_ENV
@@ -184,6 +192,5 @@ jobs:
           pip3 install --index-url https://test.pypi.org/simple --no-deps  $PACKAGE_NAME==$PACKAGE_VERSION
 
       - name: Publish Package to PyPI 🥩
-        if: github.ref == 'refs/heads/main'
         run: |
           uv publish --token ${{ secrets.AR_PYPI_API_TOKEN }} dist/*