python-package.yml

# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
# Documentation-only diffs (.md, .txt, docs/) skip unit tests but still run pre-commit.

name: Python package

on:
  push:
    branches: ["develop"]
  pull_request:
    branches: ["develop", "main"]
  workflow_call:

jobs:
  change_scope:
    runs-on: ubuntu-latest
    outputs:
      skip_tests: ${{ steps.detect.outputs.skip_tests }}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0

      - name: Detect documentation-only changes
        id: detect
        run: |
          is_documentation_only_path() {
            case "$1" in
              *.md|*.MD|*.txt|*.TXT) return 0 ;;
              docs/*|Documentation/*|documentation/*) return 0 ;;
              changelog/*) return 0 ;;
              *) return 1 ;;
            esac
          }

          # Reusable workflows and unknown events always run the full suite.
          if [ "${{ github.event_name }}" = "workflow_call" ]; then
            echo "skip_tests=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          if [ "${{ github.event_name }}" = "pull_request" ]; then
            git fetch --depth=1 origin "${{ github.event.pull_request.base.sha }}"
            mapfile -t changed < <(git diff --name-only "${{ github.event.pull_request.base.sha }}" HEAD)
          elif [ "${{ github.event_name }}" = "push" ]; then
            before="${{ github.event.before }}"
            if [ -z "$before" ] || [ "$before" = "0000000000000000000000000000000000000000" ]; then
              echo "skip_tests=false" >> "$GITHUB_OUTPUT"
              exit 0
            fi
            mapfile -t changed < <(git diff --name-only "$before" HEAD)
          else
            echo "skip_tests=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          if [ "${#changed[@]}" -eq 0 ]; then
            echo "skip_tests=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          doc_only=true
          for path in "${changed[@]}"; do
            if ! is_documentation_only_path "$path"; then
              doc_only=false
              break
            fi
          done

          if [ "$doc_only" = true ]; then
            echo "skip_tests=true" >> "$GITHUB_OUTPUT"
            echo "Documentation-only changes detected — unit tests will be skipped."
          else
            echo "skip_tests=false" >> "$GITHUB_OUTPUT"
          fi

  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.13"
      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
      - name: Install dependencies
        run: uv sync --frozen --extra dev
      - name: Run pre-commit hooks
        run: uv run pre-commit run --all-files
        env:
          # Commit-message hooks check `git log` HEAD — not meaningful in CI
          SKIP: conventional-gitmoji,commitizen
      - name: Check Ruff formatting
        run: uv run ruff format --check --force-exclude .
      - name: Check YAML formatting
        run: >-
          uv run yamllint -d "{extends: default, rules: {line-length: disable,
          document-start: disable, truthy: disable, comments: disable}}"
          .github/workflows

  build:
    needs: change_scope
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install uv
        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          # Avoid parallel matrix jobs racing on the same Actions cache reservation
          cache-suffix: py-${{ matrix.python-version }}
      - name: Install dependencies
        if: needs.change_scope.outputs.skip_tests != 'true'
        run: uv sync --frozen --extra dev --extra deploy
      - name: Documentation-only changes — unit tests skipped
        if: needs.change_scope.outputs.skip_tests == 'true'
        run: |
          echo "Only .md, .txt, or docs/ paths changed."
          echo "Skipping pytest matrix."
      - name: Test with pytest
        if: needs.change_scope.outputs.skip_tests != 'true'
        run: uv run pytest --no-cov