Continuous Integration

We make use of GitHub Actions as a Continuous Integration (CI) server for running predefined jobs, such as automated tests, in a controlled environment. Whenever certain parts of the project’s repository have changed, relevant jobs are automatically executed.

Tip

A track record of past runs can be found on GitHub in the Actions tab.

The workflow definitions of individual CI jobs can be found in YAML files located in the directory .github/workflows/. In the following, we discuss the different tasks dealt with by these workflows.

Quality Control

The following CI jobs are run automatically for all pull requests to ensure that their changes do not introduce any regressions. If one or more jobs fail, the respective pull request cannot be merged.

  • test_build.yml builds the project for each of the supported target platforms, i.e., Linux, Windows, and macOS (see Building from Source). In the Linux environment, this job does also execute all available unit and integration tests (see Testing the Code). It is run for pull requests whenever relevant parts of the project’s source code have been modified.

  • test_changelog.yml ensures that all changelog files in the project adhere to the structure that is necessary to be processed automatically when publishing a new release. This job is run for pull requests if they modify one of the changelog files.

  • test_doc.yml generates the latest documentation and checks for any broken links and spelling mistakes it contains (see Generating the Documentation) whenever relevant parts of the source code are affected by a pull request.

  • test_format.yml ensures that all source files in the project adhere to our coding style guidelines (see Code Style). This job is run automatically for pull requests whenever they include any changes affecting the relevant source files.

  • test_publish.yml ensures that the packages to be released for different architectures and Python versions can be built. The job is run for pull requests that modify relevant parts of the source code.

Automated Releases

The release process described here is fully automated via the CI jobs listed below. They are responsible for merging changes, which have been added to the code base via pull requests, to the correct release branches, updating the version numbers of these branches, and triggering releases.

  • merge_feature.yml and merge_bugfix.yml are used to merge changes that have been pushed to the feature or bugfix branch into downstream branches via pull requests (see Downstream Merges).

  • merge_release.yml is used to merge all changes included in a new release published on GitHub into upstream branches and update the version numbers of these branches (see Upstream Merges).

  • release.yml defines a job for releasing a new version of the software developed by this project (see Triggering Releases). The job can be triggered manually for one of the branches mentioned in the section Release Process. It automatically updates the project’s changelog, builds the latest documentation, and publishes a new release on GitHub.

Publishing Packages

The following CI jobs are used for building our software for different target platforms and architectures and publishing the resulting packages.

  • publish.yml is used for publishing the documentation on readthedocs and uploading pre-built packages to PyPI (see Installation). For the latter, the project is built from source for each of the target platforms and architectures. The job is run automatically when a new release was published on GitHub. It does also increment the project’s major version number and merge the release branch into its upstream branches (see Release Process).

  • publish_development.yml publishes development versions of the documentation on readthedocs and uploads development packages to Test-PyPI whenever changes to the project’s source code have been pushed to the main branch. The packages built by each of these runs are also saved as artifacts and can be downloaded as zip archives.

Maintenance

The CI jobs listed below are run periodically to perform different maintenance tasks, such as the automatic update of dependencies.

  • update_github_actions.yml checks for outdated GitHub Actions used in workflow definition files. In cases where any updates are necessary, a pull request with the respective changes is opened. If the pull request passes all necessary checks, it is merged automatically. Otherwise, manual intervention is needed.

  • update_github_runners.yml checks for outdated GitHub runners used in the project’s CI workflows. If outdated runners are found, they are automatically updated via a pull request. Manual intervention is only needed if the pull request results in any test failures.

  • update_dependencies_build.yml and update_dependencies_runtime.yml search for outdated build- and runtime dependencies in the project’s requirements.txt or pyproject.template.toml files, required by the project’s build system and for running its algorithms, respectively. In addition, the latter does also update the supported Python versions, if a new Python release is available. If any changes have been made, a pull request is opened. If all necessary checks are successful, the pull request is merged. Otherwise, manual intervention is needed.

  • update_doxyfile.yml updates the Doxygen configuration file, required for generating API documentations for C++ code, to stay up-to-date as new versions of this software are released.

Chore

The following CI jobs do not modify the project’s source code, but help with common workflows.