From fd4841b5d3b4e13bb32ffd5315eb4846cffde95b Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Thu, 10 Sep 2026 18:18:27 -0700
Subject: [PATCH] Restore stable documentation automation for maintenance
 releases

---
 .github/workflows/stable-docs.yml | 77 +++++++++++++++++++++++++++++++
 .readthedocs.yaml                 |  2 +-
 docs/contributing.rst             |  4 ++
 3 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/stable-docs.yml

diff --git a/.github/workflows/stable-docs.yml b/.github/workflows/stable-docs.yml
new file mode 100644
index 00000000..30711ff2
--- /dev/null
+++ b/.github/workflows/stable-docs.yml
@@ -0,0 +1,77 @@
+name: Update Stable Docs
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+    - main
+    - 0.65.x
+
+permissions:
+  contents: write
+
+jobs:
+  update_stable_docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v7
+      with:
+        fetch-depth: 0  # We need all commits to find docs/ changes
+    - name: Set up Git user
+      run: |
+        git config user.name "Automated"
+        git config user.email "actions@users.noreply.github.com"
+    - name: Create stable branch if it does not yet exist
+      run: |
+        if ! git ls-remote --heads origin stable | grep -qE '\bstable\b'; then
+          # Make sure we have all tags locally
+          git fetch --tags --quiet
+
+          # Latest tag that is just numbers and dots (optionally prefixed with 'v')
+          # e.g., 0.65.2 or v0.65.2 — excludes 1.0a20, 1.0-rc1, etc.
+          LATEST_RELEASE=$(
+            git tag -l --sort=-v:refname \
+            | grep -E '^v?[0-9]+(\.[0-9]+){1,3}$' \
+            | head -n1
+          )
+
+          git checkout -b stable
+
+          # If there are any stable releases, copy docs/ from the most recent
+          if [ -n "$LATEST_RELEASE" ]; then
+            rm -rf docs/
+            git checkout "$LATEST_RELEASE" -- docs/ || true
+          fi
+
+          git commit -m "Populate docs/ from $LATEST_RELEASE" || echo "No changes"
+          git push -u origin stable
+        fi
+    - name: Handle Release
+      if: github.event_name == 'release' && !github.event.release.prerelease
+      run: |
+        git fetch --all
+        git checkout stable
+        git reset --hard ${GITHUB_REF#refs/tags/}
+        git push origin stable --force
+    - name: Handle documentation update
+      if: github.event_name == 'push' && contains(github.event.head_commit.message, '!stable-docs')
+      run: |
+        git fetch origin
+        git checkout -b stable origin/stable
+        # Get the list of modified files in docs/ from the current commit
+        FILES=$(git diff-tree --no-commit-id --name-only -r ${{ github.sha }} -- docs/)
+        # Check if the list of files is non-empty
+        if [[ -n "$FILES" ]]; then
+          # Checkout those files to the stable branch to over-write with their contents
+          for FILE in $FILES; do
+            git checkout ${{ github.sha }} -- $FILE
+          done
+          git add docs/
+          git commit -m "Doc changes from ${{ github.sha }}"
+          git push origin stable
+        else
+          echo "No changes to docs/ in this commit."
+          exit 0
+        fi
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 5b30e75a..9b3f55ea 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,7 +1,7 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
     python: "3.11"
 
diff --git a/docs/contributing.rst b/docs/contributing.rst
index bddceafe..f6829248 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -274,6 +274,10 @@ You can generate the list of issue references for a specific release by copying
 
 To create the tag for the release, create `a new release <https://github.com/simonw/datasette/releases/new>`__ on GitHub matching the new version number. You can convert the release notes to Markdown by copying and pasting the rendered HTML into this `Paste to Markdown tool <https://euangoddard.github.io/clipboard2markdown/>`__.
 
+Publishing a non-prerelease also runs ``.github/workflows/stable-docs.yml``, which resets the ``stable`` branch to the release tag. Read the Docs then rebuilds the documentation at ``/en/stable/``. This workflow must be present in the release tag, including releases from maintenance branches such as ``0.65.x``. Verify that the workflow and the subsequent Read the Docs build both succeed.
+
+Between releases, include ``!stable-docs`` in a commit message on ``main`` or ``0.65.x`` to copy the documentation files changed by that commit to ``stable``. This copies whole files, so those pages must describe the stable release. Changes made only on ``stable`` are replaced by the next release; keep documentation and build configuration fixes in the release source branch too.
+
 Finally, post a news item about the release on `datasette.io <https://datasette.io/>`__ by editing the `news.yaml <https://github.com/simonw/datasette.io/blob/main/news.yaml>`__ file in that site's repository.
 
 .. _contributing_alpha_beta: