ci.yml

name: CI

on: [push, pull_request, workflow_dispatch]

# Notes on workflow security:

# This workflow was written such that the release artifacts (wheels)
# are built and published in an environment with the least additional dependencies.
# To achieve that, the execution of tests and the building of docs is done
# in separate jobs from the job that builds wheels. Both tests and docs require
# many additional PyPI packages each of which could insert malicious code into
# the built wheels if everything was running within a single job.

# Another concern is the use of third-party actions ('uses:'). In particular,
# uploaded artifacts (wheels) can be overridden in subsequent build steps/jobs.
# This is possible as actions (compared to 'run:' scripts) have access to a
# special (undocumented) artifacts token (not the regular GITHUB_TOKEN) which
# is used by the actions/upload-artifact action. See also:
# https://github.com/actions/upload-artifact/issues/197
# As a mitigation, in this workflow none of the jobs that run before and
# including the one that publishes the wheels to PyPI uses third-party actions.

# Lastly, the GITHUB_TOKEN permissions are set to read-only by default except
# for the job that deploys to GitHub Pages. In that job, a third-party action
# is used that writes to the 'gh-pages' branch of the repository.
# This will change in the near future once pages can be deployed directly
# without writing to a branch by using the new in-beta actions/deploy-pages action.
# After that, no third-party actions will be used and the token permissions are fully
# read-only.

permissions: read-all

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        config:
        # NOTE: When updating this list, also update the 'test' job!
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '2.0.*'

        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.12'
          numpy-version: '2.0.*'

        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '2.0.*'

        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.12'
          numpy-version: '2.0.*'

        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '2.0.*'

    runs-on: ${{ matrix.config.os-image }}

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: true

    - name: Set up QEMU
      if: matrix.config.python-arch == 'aarch64'
      uses: docker/setup-qemu-action@v3

    - name: Build wheels (Linux)
      if: matrix.config.os-name == 'linux'
      run: docker run --rm -e PYTHON_ARCH -e PYTHON_VERSION -e NUMPY_VERSION -v `pwd`:/io ${{ matrix.config.docker-image }} /io/.github/scripts/build-linux.sh
      env:
        PYTHON_ARCH: ${{ matrix.config.python-arch }}
        PYTHON_VERSION: ${{ matrix.config.python-version }}
        NUMPY_VERSION: ${{ matrix.config.numpy-version }}

    - name: Build wheels (macOS)
      if: matrix.config.os-name == 'mac'
      run: .github/scripts/build-macos.sh
      env:
        MACOS_MIN_VERSION: ${{ matrix.config.macos-min-version }}
        PYTHON_ARCH: ${{ matrix.config.python-arch }}
        PYTHON_VERSION: ${{ matrix.config.python-version }}
        NUMPY_VERSION: ${{ matrix.config.numpy-version }}

    - name: Setup Python (Windows)
      if: matrix.config.os-name == 'windows'
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.config.python-version }}

    - name: Build wheels (Windows)
      if: matrix.config.os-name == 'windows'
      run: .github/scripts/build-windows.ps1
      shell: pwsh
      env:
        PYTHON_VERSION: ${{ matrix.config.python-version }}
        PYTHON_ARCH: ${{ matrix.config.python-arch }}
        NUMPY_VERSION: ${{ matrix.config.numpy-version }}

    - name: Store wheels as artifacts
      uses: actions/upload-artifact@v4
      with:
        name: wheel-${{ matrix.config.os-name }}-${{ matrix.config.python-arch }}-${{ matrix.config.python-version }}
        path: dist

  test:
    strategy:
      fail-fast: false
      matrix:
        # GitHub Actions doesn't support YAML anchors,
        # so this has to be duplicated here.
        config:
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_x86_64
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '1.26.4'

        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.12'
          numpy-version: '2.0.*'
        - os-image: ubuntu-latest
          os-name: linux
          docker-image: quay.io/pypa/manylinux2014_aarch64
          python-arch: 'aarch64'
          python-version: '3.12'
          numpy-version: '1.26.4'

        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '2.0.*'
        - os-image: macos-12
          os-name: mac
          macos-min-version: '10.9'
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '1.26.4'

        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.12'
          numpy-version: '2.0.*'
        - os-image: macos-14 # M1
          os-name: mac
          macos-min-version: '11.0'
          python-arch: 'arm64'
          python-version: '3.12'
          numpy-version: '1.26.4'

        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.9'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.10'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.11'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '2.0.*'
        - os-image: windows-2019
          os-name: windows
          python-arch: 'x86_64'
          python-version: '3.12'
          numpy-version: '1.26.4'

    runs-on: ${{ matrix.config.os-image }}

    needs: build

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: true

    - name: Download wheels from artifact storage
      uses: actions/download-artifact@v4
      with:
        pattern: wheel-*
        merge-multiple: true
        path: dist

    - name: Set up QEMU
      if: matrix.config.python-arch == 'aarch64'
      uses: docker/setup-qemu-action@v3

    - name: Test wheel (Linux)
      if: matrix.config.os-name == 'linux'
      run: docker run --rm -e PYTHON_ARCH -e PYTHON_VERSION -e NUMPY_VERSION -v `pwd`:/io ${{ matrix.config.docker-image }} /io/.github/scripts/test-linux.sh
      env:
        PYTHON_ARCH: ${{ matrix.config.python-arch }}
        PYTHON_VERSION: ${{ matrix.config.python-version }}
        NUMPY_VERSION: ${{ matrix.config.numpy-version }}

    - name: Setup Python (Windows)
      if: matrix.config.os-name == 'windows'
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.config.python-version }}

    - name: Test wheel (Windows)
      if: matrix.config.os-name == 'windows'
      run: .github/scripts/test-windows.ps1
      shell: pwsh
      env:
        PYTHON_VERSION: ${{ matrix.config.python-version }}
        PYTHON_ARCH: ${{ matrix.config.python-arch }}
        NUMPY_VERSION: ${{ matrix.config.numpy-version }}

    - name: Setup Python (macOS)
      if: matrix.config.os-name == 'mac'
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.config.python-version }}

    - name: Test wheel (macOS)
      if: matrix.config.os-name == 'mac'
      run: .github/scripts/test-macos.sh
      env:
        PYTHON_ARCH: ${{ matrix.config.python-arch }}
        PYTHON_VERSION: ${{ matrix.config.python-version }}
        NUMPY_VERSION: ${{ matrix.config.numpy-version }}

  docs:
    runs-on: ubuntu-latest

    needs: build

    steps:
    - uses: actions/checkout@v4
   
    - name: Setup Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.9'

    - name: Download wheels from artifact storage
      uses: actions/download-artifact@v4
      with:
        pattern: wheel-*
        merge-multiple: true
        path: dist

    - name: Install from wheel
      run: |
        pip install --no-deps rawpy --no-index -f dist
        pip install -r dev-requirements.txt

    - name: Build docs
      run: sphinx-build -b html docs dist-docs

    - name: Store docs HTML as artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: dist-docs/

  publish-wheels:
    runs-on: ubuntu-latest

    needs: [test, docs]

    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')

    steps:
    - name: Download wheels from artifact storage
      uses: actions/download-artifact@v4
      with:
        pattern: wheel-*
        merge-multiple: true
        path: dist

    - name: Setup Python
      uses: actions/setup-python@v5
    
    - name: Upload wheels to PyPI
      run: |
        pip install twine
        twine upload -u __token__ -p ${{ secrets.PYPI_TOKEN }} --skip-existing dist/*

  publish-docs:
    runs-on: ubuntu-latest

    needs: [publish-wheels]

    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4