python-compatibility.yml

name: "Python Compatibility"

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 4 * * 6'

permissions:
  contents: read

# Only pull-request runs may be superseded. GitHub cancels a *pending* run when
# a newer one joins its group, whatever `cancel-in-progress` says, so a shared
# group for main's pushes would leave commits unvalidated; other events key on
# the run id.
concurrency:
  group: python-compatibility-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  # #1660: the matrix below, from .github/python-versions.toml -- see the job of
  # the same name in unit-tests.yml.
  python-versions:
    name: Read the Python versions
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      compatibility: ${{ steps.read.outputs.compatibility }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          sparse-checkout: |
            .github/python-versions.toml
            util/python_versions.py
          sparse-checkout-cone-mode: false
          persist-credentials: false

      - name: Read .github/python-versions.toml
        id: read
        run: python3 util/python_versions.py --github-output

  compatibility:
    # `Compat`, so `gh pr checks` cannot show two `Python 3.N` rows, this and
    # Unit Tests', with nothing to tell them apart.
    #
    # #1633's tiers. A supported leg keeps the plain name, one of ruleset
    # 23497679's required contexts. A KTLO leg is suffixed ` (KTLO)`, so no
    # required context can match it, and its steps carry `continue-on-error`,
    # as in unit-tests.yml's `test` job: job-level, a failed leg's check run
    # concluded `failure`, so every commit showed red (#1672). Nothing below
    # `requires-python`'s 3.8 runs (#2051).
    name: Compat Python ${{ matrix.python-version }}${{ matrix.ktlo && ' (KTLO)' || '' }}
    needs: [python-versions]
    runs-on: ${{ matrix.os || 'ubuntu-latest' }}
    env:
      ANNOTATION_LEVEL: ${{ matrix.ktlo && 'warning' || 'error' }}
    strategy:
      fail-fast: false
      # Both tiers, as for unit-tests.yml's `test` job (#1660), which explains
      # the `os` pins: a KTLO leg carries `ktlo: true`, and `os` where
      # `ubuntu-latest` has no setup-python build for it. A tier change edits
      # ruleset 23497679 too.
      matrix: ${{ fromJSON(needs.python-versions.outputs.compatibility) }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        id: checkout
        continue-on-error: ${{ matrix.ktlo == true }}

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        id: python
        continue-on-error: ${{ matrix.ktlo == true }}
        with:
          python-version: ${{ matrix.python-version }}

      # The install needs this leg's interpreter, and the check below needs the
      # install, as in unit-tests.yml's `test` job: on a KTLO leg a failed step
      # does not stop the job, so each one waits on the `outcome` it needs.
      # util/pip_install.py annotates a failed install, as in `test` (#1967).
      - name: Install package
        id: install
        if: ${{ steps.python.outcome == 'success' }}
        continue-on-error: ${{ matrix.ktlo == true }}
        env:
          LEG: Python ${{ matrix.python-version }}${{ matrix.ktlo && ' (KTLO, non-blocking)' || '' }}
        run: python util/pip_install.py -e .

      # One annotation saying why, so a failed leg -- an install that succeeds
      # with sources that do not compile -- is legible from the run summary; a
      # warning on a KTLO leg (#1672). Each title escapes `,` as
      # `%2C`: the runner splits a command's properties on `,`, so the KTLO
      # title would stop at "(KTLO" (actions/runner
      # src/Runner.Common/ActionCommand.cs:100, at 5f0b3ddcc).
      - name: Verify package
        id: verify
        if: ${{ steps.install.outcome == 'success' }}
        continue-on-error: ${{ matrix.ktlo == true }}
        shell: bash
        env:
          LEG: Python ${{ matrix.python-version }}${{ matrix.ktlo && ' (KTLO, non-blocking)' || '' }}
        run: |
          log="$RUNNER_TEMP/compileall.log"
          if ! python -m compileall -q pcapkit > "$log" 2>&1; then
            cat "$log"
            count=$(awk '/^\*\*\* Error compiling /{n++} END{print n+0}' "$log")
            first=$(awk '/^  File "/{sub(/^  /, ""); print; exit}' "$log")
            echo "::${ANNOTATION_LEVEL} title=pcapkit does not compile on ${LEG//,/%2C}::$count modules fail to compile, the first at ${first:-an unreported place}; see this step's log."
            exit 1
          fi
          if ! python -c 'import pcapkit; print(pcapkit.__version__)'; then
            echo "::${ANNOTATION_LEVEL} title=pcapkit does not import on ${LEG//,/%2C}::See the traceback in this step's log."
            exit 1
          fi

      # #1672: the KTLO leg's report -- the same step ends every KTLO matrix
      # job; see unit-tests.yml's `test` job for how it works.
      - name: KTLO summary
        if: ${{ !cancelled() && matrix.ktlo == true }}
        continue-on-error: ${{ matrix.ktlo == true }}
        shell: bash
        env:
          LEG: Python ${{ matrix.python-version }}${{ matrix.ktlo && ' (KTLO, non-blocking)' || '' }}
          STEPS: ${{ toJSON(steps) }}
          JOB_SUMMARY_COPY: ${{ runner.temp }}/job-summary.md
        run: /usr/bin/python3 util/leg_summary.py ktlo

      # #2030: the job's summary, for the report ci-reports.yml posts, as in
      # unit-tests.yml's `test` job: `KTLO summary` copies its lines to
      # job-summary.md, and these name the job and upload both.
      - name: Name the job summary
        if: ${{ always() }}
        continue-on-error: true
        shell: bash
        env:
          JOB_NAME: Compat Python ${{ matrix.python-version }}${{ matrix.ktlo && ' (KTLO)' || '' }}
        run: if [ -s "$RUNNER_TEMP/job-summary.md" ]; then printf '%s\n' "$JOB_NAME" > "$RUNNER_TEMP/job-summary.name"; fi

      - name: Upload the job summary
        if: ${{ always() }}
        continue-on-error: true
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: job-summary-${{ github.job }}-${{ strategy.job-index }}
          path: |
            ${{ runner.temp }}/job-summary.md
            ${{ runner.temp }}/job-summary.name
          if-no-files-found: ignore
          retention-days: 7