From 5de508f9355d00ee47eb633c57ec882f1a5a7ed0 Mon Sep 17 00:00:00 2001
From: rg936672 <162452529+rg936672@users.noreply.github.com>
Date: Mon, 27 Jan 2025 12:23:18 +0000
Subject: [PATCH 1/3] ci: add workflow to automatically test built package

Refs: #468
---
 .github/workflows/release.yml | 122 ++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 .github/workflows/release.yml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..6681851
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,122 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        type: string
+        description: Which branch to use to build the release
+        required: true
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.branch }}
+      - name: Set up base Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Install and upgrade build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade build
+      - name: Build the package
+        run: python -m build --verbose --outdir $RUNNER_TEMP/dist
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-latest
+          path: ${{ runner.temp }}/dist
+          if-no-files-found: error
+          overwrite: true
+  test:
+    name: Test package
+    needs: build
+    defaults:
+      run:
+        # Use Bash by default to avoid complications - PowerShell and Bash have
+        # different syntax for environment variables.
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+    runs-on: ${{ matrix.os }}
+    env:
+      # Set the Python version that `uv` will use for its virtual environment.
+      UV_PYTHON: ${{ matrix.python-version }}
+      # Disable implicitly syncing before running - we want to install only from the
+      # built wheel, not from the project.
+      UV_NO_SYNC: true
+    steps:
+      - name: Check out only the test files
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.branch }}
+          # Only check out the test files; this ensures we don't get any
+          # cross-contamination from the source code.
+          sparse-checkout: |
+            tests/**
+            examples/**
+          # Don't check out any files other than those specified above. (If this is
+          # set to true, it checks out files in the repo root as well.)
+          sparse-checkout-cone-mode: false
+      - name: Download built package
+        uses: actions/download-artifact@v4
+        with:
+         name: build-latest
+         path: ${{ runner.temp }}/dist
+      - name: Get wheel filename to install
+        run: |
+          # Save a list of all wheel files found in the downloaded artifact
+          find $RUNNER_TEMP/dist -type f -name '*.whl' > $RUNNER_TEMP/wheel_filename.txt
+          cat $RUNNER_TEMP/wheel_filename.txt
+          # Check that we only found one wheel file (we pipe the input in via cat to
+          # avoid printing the file name, so we can test against it)
+          test $(cat $RUNNER_TEMP/wheel_filename.txt | wc -l) -eq 1
+          # Save its location to an environment variable
+          echo "WHEEL_FILENAME=$(<$RUNNER_TEMP/wheel_filename.txt)" >> $GITHUB_ENV
+      - name: Set up uv cache directory location
+        run: echo "UV_CACHE_DIR=${{ runner.temp }}/.uv-cache" >> $GITHUB_ENV
+      - name: Restore uv cache (read-only)
+        # We don't save the cache here, as we expect this job to be run only very
+        # infrequently.
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ env.UV_CACHE_DIR }}
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}-${{ matrix.python-version }}-test
+          restore-keys: |
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}-${{ matrix.python-version }}
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+            uv-${{ runner.os }}
+      - name: Install latest versions of pip and uv
+        run: python -m pip install --upgrade pip uv
+      - name: Install test dependencies
+        run: |
+          uv venv
+          uv pip install $WHEEL_FILENAME[test]
+      - name: Debug - uv pip freeze
+        run: uv pip freeze
+      - name: Test with pytest
+        run: uv run pytest tests --ignore=tests/test_examples.py
+      # The example notebooks are slow, so only run if all other tests pass.
+      - name: Test example notebooks
+        run: uv run pytest tests/test_examples.py
+  release-github:
+    name: Create GitHub draft release
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo TODO

From 46b1cc55181a847a0af671fdeed353fbb32b043c Mon Sep 17 00:00:00 2001
From: rg936672 <162452529+rg936672@users.noreply.github.com>
Date: Mon, 27 Jan 2025 12:25:27 +0000
Subject: [PATCH 2/3] docs: update release procedure to use new GitHub workflow

Refs: #468
---
 CONTRIBUTING.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index affe1b5..3ae4bdb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -422,12 +422,18 @@ for another release:
      closed them.
 6. Update the version number in `vanguard/__init.py__`and
    `.github/ISSUE_TEMPLATE/bug_report.yml`.
-8. Once approved, merge the release branch into `main` as soon as possible.
-9. Create a release in GitHub pointing at the final commit on the release branch (that
-   is, the commit _before_ merging into `main`). If the release branch was deleted, you
-   may need to target the commit by its hash.
-10. Build and publish to PyPI and ReadTheDocs, ensuring that the code is published from
-   the same commit as the GitHub release.
+7. Create and review a pull request.
+8. Once approved, merge the release branch into `main` as soon as possible. Do _not_
+   delete the release branch when you merge the PR - only delete it once the full
+   release process has been completed.
+9. Manually trigger the "Release" action, inputting the name of the release branch.
+10. Create a release in GitHub pointing at the final commit on the release branch (that
+   is, the commit _before_ merging into `main`). Add the wheel file produced by the
+   Release action to the GitHub release as an artifact.
+11. Publish to PyPI. Ensure that the wheel and sdist uploaded are those produced by
+   the Release action.
+12. Publish to ReadTheDocs, ensuring that the documentation is built from the same
+   commit as in step 10.
 
 ## References
 

From 879e23cddb6d90e5ea91aad600d09027fe9ee5de Mon Sep 17 00:00:00 2001
From: rg936672 <162452529+rg936672@users.noreply.github.com>
Date: Wed, 29 Jan 2025 16:58:56 +0000
Subject: [PATCH 3/3] chore: fix typo

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3ae4bdb..96990c0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -420,7 +420,7 @@ for another release:
      the relevant versions.
    - Replace all issue links in the new version's sections with links to the PRs that
      closed them.
-6. Update the version number in `vanguard/__init.py__`and
+6. Update the version number in `vanguard/__init.py__` and
    `.github/ISSUE_TEMPLATE/bug_report.yml`.
 7. Create and review a pull request.
 8. Once approved, merge the release branch into `main` as soon as possible. Do _not_