Continuous Integration (CI)

Table of Contents

• Documentation workflow
• How do I write my own tests?

Peano uses GitHub Actions for continuous integration.

A workflow is a .yml file in .github/workflows/; GitHub runs it on its own hosted runners whenever its trigger fires. You find the status of all runs on the Actions page of the repository.

Note

The build and test pipelines used to run on the LRZ GitLab on our own runners on COSMA. Their definitions (.gitlab-ci.yml and the files in .continuous_integration) are still in the repository, but they are not ported to GitHub Actions yet and are not executed there. The only workflow that currently runs on GitHub is the documentation workflow below.

Documentation workflow

The file .github/workflows/doxygen.yml builds this website and publishes it at https://tobiasweinzierl.github.io/peano/. It runs

• on every push to the branch p4, and
• on demand: open the Actions tab, pick Doxygen documentation and press Run workflow.

It consists of two jobs:

• build runs on ubuntu-latest. It checks out the sources, installs doxygen, graphviz and pandoc through apt and jupyter/nbconvert through pip, and then performs the same steps that you run locally to build the documentation: python3 documentation/convert-jupyter-notebooks.py doxygen documentation/Doxyfile The notebook conversion turns the tutorial notebooks into Doxygen pages (see Tutorials Overview). Doxygen writes its output to doxygen-html/html, which the job uploads as a GitHub Pages artifact.
• deploy publishes this artifact to GitHub Pages.

Note

The repository settings have to select GitHub Actions as the source under Settings > Pages* for the deploy job to work.

If the website does not update, open the failed run in the Actions tab, and inspect the log of the step that failed. As the steps are plain shell commands, you can reproduce nearly every failure locally from the root of the repository.

How do I write my own tests?

The preferred way to add a test is to write it as a pytest test in tests/ (see Pytest-based tests for Peano's Python scripts) and to let a workflow call pytest. A minimal workflow, e.g. .github/workflows/pytest.yml, reads

name: Python unit tests
 
on:
  push:
  pull_request:
 
jobs:
  pytest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: python3 -m pip install pytest
      - run: python3 -m pytest

Plain pytest runs all fast tests, which do not compile any code. Tests that build and run Peano applications are selected through markers, e.g. python3 -m pytest -m integration tests/exaparty -k sod-1d. These tests need a compiler toolchain, and it is best to copy the setup from the documentation workflow and to extend the Install dependencies step.

Some general tips:

• A workflow is only executed if it is on the branch that triggers it, i.e. new workflows have to be pushed before they show up in the Actions tab.
• Use workflow_dispatch as additional trigger while developing a workflow, so you can start it by hand.
• Use needs: to make a job depend on another one, e.g. a test job on a build job. Jobs run on fresh machines. Pass build results between them through actions/upload-artifact and actions/download-artifact.
• Pin actions to a major version (actions/checkout@v4) as done in the existing workflow.