Improve GitHub Actions Python release workflow

Split the workflow into validation and release paths and add clearer step names and safeguards. PRs against main/master now run a validation matrix (3.10, 3.11, 3.12) that builds the package, runs twine check, and smoke-tests installing the wheel; fail-fast is disabled to surface version-specific issues. Tag pushes matching v*.*.* trigger a canonical release build (single Python 3.12) that produces dist artifacts, uploads them as workflow artifacts, and a separate publish job downloads those artifacts and uploads them to PyPI. Other improvements: minimal permissions (contents: read), explicit checkout/setup steps, pip caching enabled, comments for clarity, and use of --skip-existing when uploading to PyPI.

Author: C-Achard

.github/workflows/python-package.yml

@@ -1,27 +1,42 @@
 name: Build, validate & Release
 
+# Usage:
+# - For PRs: this workflow runs automatically to validate the package builds and installs correctly on multiple Python versions. No artifacts are published for PRs.
+# - For releases: when you push a tag like v1.2.3, this workflow runs the full matrix validation, then builds the release artifacts, and finally publishes to PyPI if all checks pass.
+
 on:
+  # Release pipeline: run only when pushing a version-like tag (e.g. v1.2.3)
   push:
     tags:
       - "v*.*.*"
+
+  # Validation pipeline: run on PRs targeting main/master (no publishing)
   pull_request:
     branches: [main, master]
     types: [opened, edited, synchronize, reopened]
 
+# This workflow only needs to read repo contents
 permissions:
   contents: read
 
 jobs:
   test_matrix:
+    # PR + tag validation: ensure the project builds and installs on multiple Pythons
     name: Test install & smoke (Py ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     strategy:
+      # Run all versions even if one fails (helps spot version-specific issues)
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
+
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      # Fetch repository sources so we can build/test
+      - name: Checkout sources
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -35,18 +50,21 @@ jobs:
             libxkbcommon-x11-0 \
             libxcb-cursor0
 
-      - name: Install tools
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install build twine wheel "packaging>=24.2"
-          cache: pip
+      # Install packaging toolchain:
+      # - build: creates wheel + sdist
+      # - twine: validates metadata and can upload (upload only happens in publish job)
+      - name: Install build tools
+        run: python -m pip install -U pip build twine
 
+      # Build distributions just to verify packaging config works on this Python
       - name: Build (for validation only)
         run: python -m build
 
+      # Validate dist metadata (README rendering, required fields, etc.)
       - name: Twine check
         run: python -m twine check dist/*
 
+      # Smoke test: install the built wheel and verify the package imports
       - name: Install from wheel & smoke test
         run: |
           python -m pip install dist/*.whl
@@ -57,50 +75,71 @@ jobs:
           PY
 
   build_release:
+    # Tag-only build: produce the "official" release artifacts once matrix passed
     name: Build release artifacts
     runs-on: ubuntu-latest
     needs: test_matrix
+    # Safety gate: only run for version tags, never for PRs/branches
     if: startsWith(github.ref, 'refs/tags/v')
+
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      # Fetch sources for the tagged revision
+      - name: Checkout sources
+        uses: actions/checkout@v6
+
+      # Use a single, modern Python for the canonical release build
+      - name: Set up Python (release build)
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
+      # Install build + validation tooling
       - name: Install build tools
         run: python -m pip install -U pip build twine
 
+      # Produce both sdist and wheel in dist/
       - name: Build distributions
         run: python -m build
 
+      # Re-check metadata on the final artifacts we intend to publish
       - name: Twine check
         run: python -m twine check dist/*
 
+      # Store dist/ outputs so the publish job uploads exactly what we built here
       - name: Upload dist artifacts
         uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/*
 
   publish:
+    # Tag-only publish: download built artifacts and upload them to PyPI
     name: Publish to PyPI (API token)
     runs-on: ubuntu-latest
     needs: build_release
+    # Safety gate: only run for version tags
     if: startsWith(github.ref, 'refs/tags/v')
+
     steps:
+      # Retrieve the exact distributions produced in build_release
       - name: Download dist artifacts
         uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist
 
-      - uses: actions/setup-python@v6
+      # Set up Python (only needed to run Twine)
+      - name: Set up Python (publish)
+        uses: actions/setup-python@v6
         with:
           python-version: "3.x"
 
+      # Install twine for uploading
       - name: Install Twine
         run: python -m pip install -U twine
 
+      # Upload to PyPI using an API token stored in repo secrets.
+      # --skip-existing avoids failing if you re-run a workflow for the same version.
       - name: Publish to PyPI
         env:
           TWINE_USERNAME: __token__