Skip to content

Latest commit

 

History

History
121 lines (90 loc) · 3.88 KB

continuous-integration.md

File metadata and controls

121 lines (90 loc) · 3.88 KB
Raw

Ivy logo

Continuous integration with GitHub Actions

Continuous integration (CI) is a software engineering practice often used where people working together on a project frequently merge their work. An automated system then builds and tests the changes, ensuring that they work together.

CSDMS uses the continuous integration service GitHub Actions. What this means in practice is that every time a pull request is submitted to a repository, the jobs designated in the GitHub Actions configuration file(s) are performed. While this varies from project to project, it typically includes building and testing the software in the pull request on Linux, macOS, and Windows.

The Ivy repository uses CI: https://github.com/csdms/ivy/actions. The original Actions configuration file, test.yml, used for the Ivy repository looks like:

name: Test

on: [push, pull_request]

jobs:

  test:
    if:
      github.event_name == 'push' ||
      github.event.pull_request.head.repo.full_name != github.repository

    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.9", "3.10", "3.11", "3.12"]

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

    defaults:
      run:
        shell: bash -l {0}

    steps:
      - uses: actions/checkout@v4
      - uses: conda-incubator/setup-miniconda@v3
        with:
          python-version: "${{ matrix.python-version }}"
          miniforge-variant: Mambaforge
          miniforge-version: latest

      - name: Install nox
        run: pip install nox

      - name: Test
        run: nox -s test

  test-notebooks:

    if:
      github.event_name == 'push' ||
      github.event.pull_request.head.repo.full_name != github.repository

    name: Test the notebooks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: conda-incubator/setup-miniconda@v3
        with:
          python-version: "3.11"
          miniforge-variant: Mambaforge
          miniforge-version: latest

      - name: Install nox
        run: pip install nox

      - name: Test
        env:
          MPLBACKEND: "Agg"
          OPENTOPOGRAPHY_API_KEY: ${{ secrets.OPENTOPOGRAPHY_API_KEY }}
        run: nox -s test-notebooks --python "3.11"

In this configuration file, we instruct Actions to run the test and test-notebooks jobs on Linux, macOS, and Windows, for a set of Python versions, but only on pushes and external pull requests to the repository. If anything fails in this process, Actions stops and issues an error message.

Check the history of runs of the test and test-notebooks jobs on the Ivy repository.

For more comprehensive examples of Actions configuration files, including multiple jobs, see, e.g., landlab, babelizer, and bmi-example-python.

Summary

Continuous integration is used in team projects to help keep local repositories synchronized across the team. It's useful even in individual projects, though, because it can be configured to build, test, and run a project on each push or pull request to a repository, alerting a developer when a build or a test fails.

Resources

Best Practices in Software Development | Previous: Unit testing with pytest Next: Collaborative projects ("Gitiquette")