cicd.yml

# Docs:
# https://help.github.com/en/actions/automating-your-workflow-with-github-actions



name: CI


on:
  push:
    branches: ["trunk"]
  pull_request:
    branches: ["*"]


jobs:

  lint:

    name: Linters

    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:

      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: System Python Information
        uses: twisted/python-info-action@v1

      - name: Set up Tox environment
        run: |
          pip install tox
          tox run -e lint --notest

      - name: Tox Python Information
        uses: twisted/python-info-action@v1
        with:
          python-path: .tox/lint/*/python

      - name: Run Linters
        run: tox run -e lint


  mypy:

    name: Mypy (static type checker)

    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:

      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: System Python Information
        uses: twisted/python-info-action@v1

      - name: Set up Tox environment
        run: |
          pip install tox
          tox run -e mypy --notest

      - name: Tox Python Information
        uses: twisted/python-info-action@v1
        with:
          python-path: .tox/mypy/*/python

      - name: Run Mypy
        run: tox run -e mypy


  docs:

    name: Build documentation

    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:

      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: System Python Information
        uses: twisted/python-info-action@v1

      - name: Set up Tox environment
        run: |
          pip install tox
          tox run -e docs --notest

      - name: Tox Python Information
        uses: twisted/python-info-action@v1
        with:
          python-path: .tox/docs/*/python

      - name: Build documentation
        run: tox run -e docs


  docs-linkcheck:

    name: Documentation link check

    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:

      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: System Python Information
        uses: twisted/python-info-action@v1

      - name: Set up Tox environment
        run: |
          pip install tox
          tox run -e docs-linkcheck --notest

      - name: Tox Python Information
        uses: twisted/python-info-action@v1
        with:
          python-path: .tox/docs-linkcheck/*/python

      - name: Check for broken links in documentation
        run: tox run -e docs-linkcheck


  packaging:
    name: Packaging

    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:

      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: System Python Information
        uses: twisted/python-info-action@v1

      - name: Set up Tox environment
        run: |
          pip install tox
          tox run -e packaging --notest

      - name: Tox Python Information
        uses: twisted/python-info-action@v1
        with:
          python-path: .tox/packaging/*/python

      - name: Check packaging
        run: tox run -e packaging


  unit:
    name: "Py:${{ matrix.python-version }} - Tw:${{ matrix.twisted-version }} - ${{ matrix.os }}"

    runs-on: ${{ matrix.os }}
    timeout-minutes: 30
    continue-on-error: ${{ matrix.optional }}
    strategy:
      matrix:
        os: ["ubuntu-latest"]
        python-version: ["3.9", "3.10", "3.11"]
        twisted-version: ["21.2", "22.1", "23.8"]
        tox-prefix: ["coverage"]
        optional: [false]
        include:
          - os: "ubuntu-latest"
            python-version: "pypy-3.9"
            twisted-version: "23.8"
            tox-prefix: "test"
            optional: false
          - os: "ubuntu-latest"
            python-version: "3.12.0"
            twisted-version: "23.8"
            tox-prefix: "test"
          - os: "ubuntu-latest"
            python-version: "3.13.0"
            twisted-version: "24.10"
            tox-prefix: "test"

    steps:

      - name: Checkout source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}

      - name: System Python Information
        uses: twisted/python-info-action@v1

      - name: Translate Python version to Tox environment
        shell: python
        run: |
          from os import environ
          from pathlib import Path

          py = "${{ matrix.python-version }}"
          py = "".join(py.split(".")[:2])   # Combine major/minor, toss rest
          py = py.replace("pypy-", "py")    # For Pypy: have a litte less py

          tw = "${{ matrix.twisted-version }}"
          tw = tw.replace(".", "")

          env = f"${{ matrix.tox-prefix }}-py{py}-tw{tw}"

          print(f"TOX_ENV={env}")

          p = Path(environ["GITHUB_ENV"])
          f = p.open(mode="a")
          f.write(f"TOX_ENV={env}\n")

      - name: Set up Tox environment
        run: |
          pip install tox
          tox run -e ${TOX_ENV} --notest

      - name: Tox Python Information
        uses: twisted/python-info-action@v1
        with:
          python-path: .tox/${TOX_ENV}/*/python

      - name: Run unit tests
        run: tox run -e ${TOX_ENV}

      - name: Upload Trial log artifact
        if: ${{ failure() }}
        uses: actions/upload-artifact@v3
        with:
          name: trial
          path: .tox/${TOX_ENV}/log/trial.log

      # Use the latest supported Python version for combining coverage to
      # prevent parsing errors in older versions when looking at modern code.
      - uses: "actions/setup-python@v4"
        with:
          python-version: "3.11"

      - name: "Upload coverage to Codecov"
        uses: "codecov/codecov-action@v3"
        if: ${{ matrix.tox-prefix == 'coverage' }}
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          env_vars: GITHUB_REF,GITHUB_COMMIT,GITHUB_USER,GITHUB_WORKFLOW
          fail_ci_if_error: true
        env:
          GITHUB_REF: ${{ github.ref }}
          GITHUB_COMMIT: ${{ github.sha }}
          GITHUB_USER: ${{ github.actor }}
          GITHUB_WORKFLOW: ${{ github.workflow }}

  # Helper so that on GitHub repo settings we can configure to single job.
  # Then required jobs can be updated directly form the code,
  # without having to go the GitHub repo setting -> Protected branch
  # and all the clicking.
  klein-required:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: always()
    # Add here the jobs that should block the merge of a PR.
    needs:
      - lint
      - mypy
      - docs
      - docs-linkcheck
      - packaging
      - unit
    steps:
      - name: Require all successes
        shell: python3 {0}
        env:
          RESULTS: ${{ toJSON(needs.*.result) }}
        run: |
          import json
          import os
          import sys
          results = json.loads(os.environ["RESULTS"])
          sys.exit(0 if all(result == "success" for result in results) else 1)