python-api-compatibility.yml

name: Python - API Compatibility

on:
  pull_request_target:
    branches: ["main"]
    types: [opened, synchronize, reopened, labeled, unlabeled]
    paths:
      - "python/**"
      - ".github/scripts/check_python_api_compatibility.py"
      - ".github/workflows/python-api-compatibility.yml"

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  api-compatibility:
    name: Public API Compatibility
    runs-on: ubuntu-latest
    continue-on-error: true
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.pull_request.base.sha }}
          fetch-depth: 1
          persist-credentials: false

      - name: Set up uv
        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
        with:
          enable-cache: false
          version-file: "python/pyproject.toml"
          python-version: "3.13"

      - name: Compare public API with the PR base
        working-directory: ${{ runner.temp }}
        env:
          BREAKING_CHANGE_ACKNOWLEDGED: ${{ contains(github.event.pull_request.labels.*.name, 'breaking change') }}
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          UV_NO_CONFIG: "1"
        shell: bash
        run: |
          skip_comparison() {
            local reason="$1"
            echo "::notice title=Python public API compatibility::$reason"
            {
              echo "## Python public API compatibility"
              echo
              echo "Comparison skipped: $reason"
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          }

          set +e
          git ls-remote \
            --exit-code \
            --refs \
            "https://github.com/$GITHUB_REPOSITORY.git" \
            "refs/pull/$PR_NUMBER/merge" > /dev/null
          ref_status=$?
          set -e
          if (( ref_status == 2 )); then
            skip_comparison "GitHub has not produced a synthetic merge ref for the current pull request head."
          fi
          if (( ref_status != 0 )); then
            echo "Failed to query the pull request merge ref (exit $ref_status)." >&2
            exit "$ref_status"
          fi

          git -C "$GITHUB_WORKSPACE" fetch \
            --no-tags \
            --no-recurse-submodules \
            --depth=2 \
            "https://github.com/$GITHUB_REPOSITORY.git" \
            "refs/pull/$PR_NUMBER/merge"

          MERGE_SHA="$(git -C "$GITHUB_WORKSPACE" rev-parse --verify 'FETCH_HEAD^{commit}')"
          BASE_SHA="$(git -C "$GITHUB_WORKSPACE" rev-parse "$MERGE_SHA^1")"
          HEAD_SHA="$(git -C "$GITHUB_WORKSPACE" rev-parse "$MERGE_SHA^2")"
          if [[ "$HEAD_SHA" != "$EXPECTED_HEAD_SHA" ]]; then
            skip_comparison "GitHub's synthetic merge ref is not current for pull request head $EXPECTED_HEAD_SHA."
          fi

          PR_SOURCE="$RUNNER_TEMP/pr-source"
          mkdir "$PR_SOURCE"
          git -C "$GITHUB_WORKSPACE" archive "$MERGE_SHA" python |
            tar -x -C "$PR_SOURCE"
          if [[ -n "$(find "$PR_SOURCE/python" -type l -print -quit)" ]]; then
            echo "Refusing to analyze pull request source containing symbolic links." >&2
            exit 1
          fi

          git -C "$GITHUB_WORKSPACE" show "$BASE_SHA:.github/scripts/check_python_api_compatibility.py" \
            > "$RUNNER_TEMP/check_python_api_compatibility.py"
          if git -C "$GITHUB_WORKSPACE" cat-file -e \
            "$BASE_SHA:python/tooling/requirements-api-compatibility.txt" 2>/dev/null; then
            git -C "$GITHUB_WORKSPACE" show \
              "$BASE_SHA:python/tooling/requirements-api-compatibility.txt" \
              > "$RUNNER_TEMP/python-api-compatibility-requirements.txt"
          else
            git -C "$GITHUB_WORKSPACE" show "$BASE_SHA:python/pyproject.toml" \
              > "$RUNNER_TEMP/python-base-pyproject.toml"
            python3 - "$RUNNER_TEMP/python-base-pyproject.toml" \
              > "$RUNNER_TEMP/python-api-compatibility-requirements.txt" <<'PY'
          import sys
          import tomllib

          with open(sys.argv[1], "rb") as pyproject_file:
              dev_dependencies = tomllib.load(pyproject_file)["dependency-groups"]["dev"]
          requirements = [
              dependency for dependency in dev_dependencies if dependency.startswith("griffe")
          ]
          if len(requirements) != 1:
              raise SystemExit("Expected exactly one Griffe development dependency")
          print(requirements[0])
          PY
          fi

          griffe_requirement="$(
            python3 - "$RUNNER_TEMP/python-api-compatibility-requirements.txt" <<'PY'
          import sys

          requirements = [
              line.strip()
              for line in open(sys.argv[1], encoding="utf-8")
              if line.strip() and not line.lstrip().startswith("#")
          ]
          if len(requirements) != 1:
              raise SystemExit("Expected exactly one Griffe tool requirement")
          print(requirements[0])
          PY
          )"

          args=(
            --base-sha "$BASE_SHA"
            --current-source "$PR_SOURCE"
            --repo "$GITHUB_WORKSPACE"
          )
          if [[ "$BREAKING_CHANGE_ACKNOWLEDGED" == "true" ]]; then
            args+=(--acknowledge-breaking-changes)
          fi

          uv --no-config run \
            --no-project \
            --with "$griffe_requirement" \
            python "$RUNNER_TEMP/check_python_api_compatibility.py" "${args[@]}"