build.yml

###
# Build and validate the project.
##
on:
  pull_request:
    branches: [main]
  schedule:
    # Run continuous integration on the 15th day of each quarter, to see
    # if maintenance is necessary (e.g., updating dependencies).
    - cron: "15 10 15 */3 *"
  workflow_call:
env:
  FORCE_COLOR: true
  PIP_NO_INPUT: true
  PIP_DISABLE_PIP_VERSION_CHECK: true
permissions: {}  # Explicitly set permissions on each job.
jobs:
  support:
    name: Check support policy.
    runs-on: ubuntu-latest
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version-file: .default-python-version
          cache: pip
      - name: Check compliance with the support policy.
        run: |
          python -Im pip install --quiet .[ci]
          python -Im nox \
            --non-interactive \
            --session support
  lint:
    name: Run lint.
    runs-on: ubuntu-latest
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version-file: .default-python-version
          cache: pip
      - name: Run the linter.
        run: |
          python -Im pip install --quiet .[ci]
          python -Im nox \
            --non-interactive \
            --session lint
  docs:
    name: Build and test docs.
    runs-on: ubuntu-latest
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
        with:
          # Fetch all history as the job needs the pull request's full
          # branch to check that the changelog has been updated.
          fetch-depth: 0
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version-file: .default-python-version
          cache: pip
      - name: Check the changelog has been updated.
        if: |
          github.event_name == 'pull_request'
          && github.base_ref == 'main'
          && github.head_ref != 'main'
        run: |
          if git diff \
              --name-only \
              origin/main HEAD \
            | grep \
              --quiet \
              --fixed-strings \
              --line-regexp \
              "CHANGELOG.rst";
          then
              echo "Success! The pull request updates the changelog."
          else
              echo "Failure! The pull request doesn't update the changelog."
              exit 1
          fi
      - name: Build and test the documentation.
        run: |
          python -Im pip install --quiet .[ci]
          python -Im nox \
            --non-interactive \
            --session docs
      - name: Upload the GitHub Pages artifact.
        uses: actions/upload-pages-artifact@v3
        with:
          name: docs
          path: docs/_build/html/
          retention-days: 90
  test:
    name: Run tests.
    runs-on: ubuntu-latest
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version-file: .default-python-version
          cache: pip
      - name: Run the tests.
        run: |
          python -Im pip install --quiet .[ci]
          python -Im nox \
            --non-interactive \
            --session test
  package:
    name: Package the source.
    runs-on: ubuntu-latest
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version-file: .default-python-version
          cache: pip
      - name: Build the distribution package.
        run: |
          python -Im pip install --quiet .[ci]
          python -Im nox \
            --non-interactive \
            --session package
      - name: List the packages' contents.
        run: |
          for build in sdist wheel; do
            mkdir "dist/${build}/"

            if [[ "${build}" == "sdist" ]]; then
              tar -x --directory "dist/${build}/" --file dist/*.tar.gz
            elif [[ "${build}" == "wheel" ]]; then
              unzip -qq -d "dist/${build}/" dist/*.whl
            else
              echo "Unrecognized build."
              exit 1
            fi

            echo "${build} files:"
            find \
              "dist/${build}" \
              -type f \
              -exec echo {} \; \
            | cut -d'/' -f3- \
            | sort \
            | awk '{ print "  " $0 } END { print "" }'

            rm -rf "dist/${build}/"
          done
      - name: Upload the package artifact.
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          if-no-files-found: error
          compression-level: 0  # packages are already compressed.
  matrix:
    name: Compute test matrix.
    runs-on: ubuntu-latest
    outputs:
      python-versions: ${{ steps.get-python-versions.outputs.python-versions }}
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version-file: .default-python-version
          cache: pip
      - name: Build the test matrix from available nox sessions.
        id: get-python-versions
        run: |
          python -Im pip install --quiet .[ci]
          PYTHON_VERSIONS=$( \
            python -Im \
              nox \
                --session testpackage \
                --list \
                --json \
              | jq \
                --raw-output \
                '.[].python' \
              | sort --version-sort \
              | uniq \
              | jq \
                --raw-input \
                --slurp \
                --compact-output \
                'split("\n")[:-1]' \
          )
          echo "python-versions=${PYTHON_VERSIONS}" | tee -a "${GITHUB_OUTPUT}"
  testpackage:
    name: Test package with Python ${{ matrix.python-version }}.
    needs:
      - package
      - matrix
    strategy:
      fail-fast: false
      matrix:
        python-version: ${{ fromJson(needs.matrix.outputs.python-versions) }}
    runs-on: ubuntu-latest
    steps:
      - name: Clone the repo.
        uses: actions/checkout@v4
      - name: Install Python.
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - name: Download the package artifact.
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - name: Run tests on the package with Python ${{ matrix.python-version }}.
        env:
          PYTHON_VERSION: ${{ matrix.python-version }}
        # NOTE: Since the package job builds the wheel from the sdist,
        # test the wheel as it should cover both.
        run: |
          python -Im pip install --quiet .[ci]
          python -Im nox \
            --non-interactive \
            --session "testpackage-${PYTHON_VERSION}" \
            -- \
            dist/*.whl
  verify:
    name: Verify all checks passed.
    if: always()
    needs:
      - support
      - lint
      - docs
      - test
      - package
      - matrix
      - testpackage
    runs-on: ubuntu-latest
    steps:
      - name: Verify that all checks passed successfully.
        uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe  # v1.2.2
        with:
          jobs: ${{ toJSON(needs) }}