ci.yaml

# Try to get a short workflow name and a job name that start with Python
# version to make it easier to check the status inside GitHub UI.
#
# When using external actions check that the external repos are permitted via
# the GitHub configuration at https://github.com/twisted/twisted/settings/actions
#
name: CI

on:
  push:
    branches:
      - trunk
    tags:
      - '*'

  pull_request:
    branches: [ trunk ]

permissions:
  contents: read

# Only have a run a single parallel for each branch.
# Runs for trunk are queues.
# Older runs for non-trunk branches are cancelled and the jobs are executed
# only for the latest push to the branch.
concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/trunk' }}


defaults:
  run:
    shell: bash

env:
  # The default values in the job generated by the matrix.
  DEFAULT_PYTHON_VERSION: '3.11'

jobs:
  testing:
    # We can't use `env.*` in the job name, only in the steps.
    name: cpython-${{ matrix.python-version }}
    runs-on: 'ubuntu-latest'
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
        allow-prereleases: true

    - name: Test build
      run: pipx run --python=python build .

    - name: Install dependencies
      run: |
        python -m pip install --upgrade twisted coverage build

    - name: Test build on each supported python
      run: python -m build .

    - name: Test code
      run: |
        coverage run -m twisted.trial constantly
        mv .coverage .coverage.${{ matrix.python-version }}

    - name: Upload coverage data
      uses: actions/upload-artifact@v3
      with:
        name: coverage-data
        path: .coverage.*
        if-no-files-found: error # 'warn' or 'ignore' are also available.


  coverage:
    name: Combine & check coverage.
    needs: testing
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v4
      with:
        # Use latest Python, so it understands all syntax.
        python-version: 3.11

    - run: python -Im pip install --upgrade coverage[toml]

    - uses: actions/download-artifact@v3
      with:
        name: coverage-data

    - name: Combine coverage & fail if it's <100%.
      run: |
        python -Im coverage combine
        python -Im coverage html --skip-covered --skip-empty

        # Report and write to summary.
        python -Im coverage report --format=markdown >> $GITHUB_STEP_SUMMARY

        # Report again and fail if under 100%.
        python -Im coverage report --fail-under=100


  static-checks:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
      with:
        # Need full history for various diff checks to work.
        fetch-depth: 0

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '${{ env.DEFAULT_PYTHON_VERSION }}'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pyflakes

    - name: Run the checks
      run: |
        python --version
        pyflakes constantly


  apidocs:
    name: API docs build
    runs-on: ubuntu-22.04
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pydoctor

    - name: Run pydoctor
      run: |
        pydoctor --project-name constantly constantly


  # Used for various release automation.
  # This is also executed for each PR to exercise the release as much
  # as possible and reduce the possibility of finding bugs in the release
  # process late in the release cycle,
  # The files are published only when a tag is created.
  release-publish:
    name: Check release and publish on twisted-* tag
    runs-on: 'ubuntu-latest'
    permissions:
      # IMPORTANT: this permission is mandatory for trusted publishing
      id-token: write

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '${{ env.DEFAULT_PYTHON_VERSION }}'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade build

    - name: Build
      run: |
        rm -rf dist/*
        python -m build .

    - name: Files to be pushed to PyPi
      run: ls -R dist/

    - name: Check matched tag version and branch version - on tag
      if: startsWith(github.ref, 'refs/tags/')
      run: |
        python -Im pip install --upgrade pep517
        python admin/check_tag_version_match.py "${{ github.ref }}"

    - name: Publish to PyPI - on tag
      if: startsWith(github.ref, 'refs/tags/')
      uses: pypa/gh-action-pypi-publish@release/v1


  # We have this job so that the PR can be blocked on a single job.
  # In this way, each time a job is modified,
  # we don't have to go to GitHub UI and reconfigure branch protection.
  # See GitHub support answer for this hack.
  # https://gist.github.com/altendky/2e3483a1f7e1ba21cc97de75db9b7d1c
  all-successful:
    # Is very important to force running this always, as otherwise it will be
    #  skipped by default.
    if: always()
    runs-on: ubuntu-latest
    # Here should be the list of all the other jobs defined in this file.
    needs:
      - testing
      - coverage
      - apidocs
      - static-checks
      - release-publish
    steps:
      - name: Require all successes
        shell: python
        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)