feat: modernize Python tooling (pyproject.toml + uv + semantic-release)

.github/workflows/ci.yml

@@ -6,6 +6,8 @@ on:
   pull_request:
     branches:
     - '**'
+  # So the release workflow can run CI before cutting a release.
+  workflow_call:
 
 
 jobs:
@@ -20,21 +22,25 @@ jobs:
 
     steps:
     - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-    - name: Setup python
-      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
       with:
+        # setuptools-scm needs real tag history to compute a version; a default
+        # shallow/single-commit checkout can't see any tags, so every build in
+        # this job would otherwise silently use fallback_version instead of the
+        # actual released version.
+        fetch-depth: 0
+    - name: Install uv
+      uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      with:
+        enable-cache: true
         python-version: ${{ matrix.python-version }}
 
-    - name: Install pip
-      run: pip install -r requirements/pip.txt
-
     - name: Install Dependencies
-      run: pip install -r requirements/ci.txt
+      run: uv sync --group ci
 
     - name: Run Tests
       env:
         TOXENV: ${{ matrix.toxenv }}
-      run: tox
+      run: uv run tox
 
     - name: Run coverage
       if: matrix.python-version == '3.12' && matrix.toxenv == 'django42'

.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Semantic Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  run_ci:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: run_ci
+    runs-on: ubuntu-latest
+    if: github.ref_name == 'main'
+    concurrency:
+      group: ${{ github.workflow }}-release-${{ github.ref_name }}
+      cancel-in-progress: false
+
+    permissions:
+      contents: write
+
+    steps:
+      # Note: We checkout the repository at the branch that triggered the workflow.
+      # Python Semantic Release will automatically convert shallow clones to full clones
+      # if needed to ensure proper history evaluation. However, we forcefully reset the
+      # branch to the workflow sha because it is possible that the branch was updated
+      # while the workflow was running, which prevents accidentally releasing un-evaluated
+      # changes.
+      - name: Setup | Checkout Repository on Release Branch
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Setup | Force release branch to be at workflow sha
+        run: |
+          git reset --hard ${{ github.sha }}
+
+      - name: Action | Semantic Version Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@350c48fcb3ffcdfd2e0a235206bc2ecea6b69df0 # v10.5.3
+        with:
+          github_token: ${{ secrets.OPENEDX_SEMANTIC_RELEASE_GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"
+          changelog: "false"
+
+      - name: Publish | Upload to GitHub Release Assets
+        uses: python-semantic-release/publish-action@310a9983a0ae878b29f3aac778d7c77c1db27378 # v10.5.3
+        if: steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{ secrets.OPENEDX_SEMANTIC_RELEASE_GITHUB_TOKEN }}
+          tag: ${{ steps.release.outputs.tag }}
+
+      - name: Upload | Distribution Artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: steps.release.outputs.released == 'true'
+        with:
+          name: distribution-artifacts
+          path: dist
+          if-no-files-found: error
+
+    outputs:
+      released: ${{ steps.release.outputs.released || 'false' }}
+      version: ${{ steps.release.outputs.version }}
+
+  publish_to_pypi:
+    runs-on: ubuntu-latest
+    needs: release
+    if: github.ref_name == 'main' && needs.release.outputs.released == 'true'
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Setup | Download Build Artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: distribution-artifacts
+          path: dist
+
+      - name: Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

.readthedocs.yaml

@@ -5,16 +5,20 @@
 # Required
 version: 2
 
+# uv isn't natively supported by Read the Docs, so drive the whole build
+# ourselves via a custom command (RTD's documented escape hatch for tools
+# it doesn't integrate with directly). Note: this gives up RTD's native
+# fail_on_warning/pdf/epub format support -- -W below replicates
+# fail_on_warning, but PDF/EPUB output would need a separate LaTeX-toolchain
+# setup that RTD otherwise provisions automatically for the `formats:` key.
 build:
-  os: "ubuntu-lts-latest"
+  os: ubuntu-24.04
   tools:
     python: "3.12"
+  commands:
+    - pip install uv
+    - uv sync --group doc
+    - uv run sphinx-build -W -b html docs/ $READTHEDOCS_OUTPUT/html
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  fail_on_warning: true
-
-python:
-  install:
-    - requirements: requirements/doc.txt