Continuous integration

Continuous integration (CI) is about commits being merged frequently, resulting in new features being released frequently. When proposing new changes to the code base a pull request is opened. When a new commit in that pull request, a series of tests will be done to make sure that this commit is error-free and robust in different environments. This process drive each new development through building, testing, quality checking.

graph LR
    A[New development]-->B[Continuous integration]
    B-->C[Merge]

This page contains an extensive explanation on how the Ribasim continuous integration works.

1 GitHub Actions

With GitHub Actions, GitHub provides their own continuous integration service. They include the following checks:

  • Julia Run Testmodels: This is to make sure all the test models can be run successfully
  • Julia Tests: Runs Julia unit tests on multiple platforms
  • Docs: Builds the documentation and executes the examples
  • Pre-commit: Checks Python code quality with linters and enforces formatting
  • Python codegen: Makes sure code generation is still up to date by checking that code generation wouldn’t change any files
  • Mypy: Runs mypy on our Python codebase to check types
  • Ribasim Python tests: Runs Ribasim Python tests on multiple platforms and multiple Python versions
  • QGIS Tests: Runs QGIS unit tests

The Github CI configuration is stored in version control, and can be found in the .github folder.

One can skip running the CI using [skip ci] in the git commit message.

2 TeamCity

Ribasim has another cloud-based CI service based on TeamCity. TeamCity interacts with GitHub and manages the release process.

graph LR
    A[TeamCity]-->|Monitoring|B[GitHub]
    A-->C(Release)

The Teamcity CI configuration itself is also stored in version control, and can be found in the .teamcity folder. Note that changes are only applied once merged to the main branch. One can test the validity of their local configuration with mvn teamcity-configs:generate (requiring a local installation of maven).

Like Github, one can skip running the Teamcity CI by starting the git commit message with [skip ci].

2.1 Conditions of using TeamCity

TeamCity only runs workflows with the following conditions:

  • When the workflow would take too long to run on GitHub Action
  • When the release depends on the artifacts of the workflow.
  • When other TeamCity projects depend on artifacts of Ribasim (e.g. iMOD coupler)

2.2 Release process

In the release, we include the generated testmodels, Ribasim CLI on Windows and Linux, Ribasim QGIS, and the source code.

We have the following pipeline to generate artifects for releasing:

  • Generate Testmodels: produces generated_testmodels artifact which is part of the release.
  • Make GitHub Release: uses artifacts and makes the release. TeamCity constantly monitors the GitHub repository. When a tag starts with v20 is added, it triggers the release process.
  • Build Ribasim: builds library and executable of Ribasim on Linux and Windows. The artifacts are tested in Test Ribasim Binaries and used by iMOD Coupler.
  • Test Ribasim Binaries: tests libribasim artifact and ribasim_cli artifact on Linux and Windows
Note

Make GitHub Release does not publish artifacts of “Test Ribasim Binaries”. It only publishes artifacts of “Build Ribasim” if the beforementioned tests pass.

graph LR
    A[Make GitHub Release]-->B(Release)
    F[Generate Testmodels]-->A
    G[Make QGIS plugin]-->A
    H[Build Ribasim]---D[Test Ribasim Binaries]
    D-->A

3 MinIO

MinIO is S3 compatible object storage. We have a MinIO instance running at Deltares, which has a bucket called ribasim that we use for storage. The bucket resides at https://s3.deltares.nl/ribasim/ and with the right permissions can be managed at https://s3-console.deltares.nl/browser/ribasim.

The bucket is private, but folders can be set to public. For instance the doc-image folder is public, and is used to host image that are part of our documentation. This way we don’t need to store images in the repository.

Some of the Pixi tasks, like those running integration tests, also depend on a task called s3-download that will download reference data from MinIO. For this to work the access keys need to be set up at the S3 Console. Go to https://s3-console.deltares.nl/access-keys, create a personal access key, and store the access key and secret key securely. Now make a copy of .env.default in the root of the repository, name it .env. In this file you can fill in the values of your access key and secret key. These will then be used in the s3-download task.