Release process

1 What is a release

The Ribasim repository contains several components, e.g., the Julia core, the Python tooling and QGIS plugin. The components are currently only guaranteed to work together if they have the same version number. Therefore we release Ribasim as a collection of all the components at once, all carrying the same version number. For maximum interoperability it is suggested to only release all components together, and not individually.

2 Release steps

This section provides a guide for developers to follow when preparing a new release.

2.1 Pre-release checks

Before starting the release process, ensure that all tests are passing and that all features intended for the release are complete and merged into the main branch.

2.2 Update version numbers of the components

Determine the new version number like 2023.1.0, filling in the current year, a bumped MINOR number for normal releases and a bumped MICRO number for non-breaking, hotfix releases. This follows YYYY.MINOR.MICRO from calver.

Create a branch that starts with release, like release-2023.1.0. It needs to start with release to trigger extra TeamCity checks.

Update the version numbers in the repository to the new version number. See also the latest Ribasim release. Use find and replace to update all locations. Only update the lines in pixi.lock that refer to Ribasim packages, to avoid accidentally changing the version number of dependencies that happen to have the same version number. Don’t change the old version numbers in changelog.qmd.

2.3 Update the changelog

The docs/changelog.qmd file, hosted on ribasim.org/changelog, records the most important changes for users. Review the commits since the latest Ribasim release to make sure these are listed. Change the “Unreleased” section to the new version number and date, and create a new empty “Unreleased” section at the top.

2.4 Submit a pull request

Now submit a pull request with the updated the version numbers and changelog.

2.5 Create a new release

When the pull request is merged to main, checkout the commit that updates the version numbers.

Create a new tag, which is the letter v followed by the version number, like, v2023.8.0.

This can be done by executing:

git tag <tagname>

Then push the tags:

git push --tags

This will trigger a workflow on TeamCity that will publish a new release on GitHub as soon as it is finished. You can follow the progress here. It also auto-generates a changelog. You need to edit that by moving the auto-generated contents, except the “Full Changelog” link, in a collapsed details block as shown below.

<details>
<summary>
All changes
</summary>

# Put GitHub flavored markdown here

</details>

Now copy the manually edited changelog entry from changelog.qmd above the details, such that the edited changelog can be seen both from our documentation as well as GitHub releases.

2.6 Release the Ribasim Python packages to PyPI

To be able to install packages with pip, they need to be released on the Python Package Index (PyPI). In order to publish Ribasim Python or Ribasim API follow the following steps:

Open a terminal and run pixi run publish-ribasim-python
Open a terminal and run pixi run publish-ribasim-api

2.7 QGIS manual testing

Our continuous integration (CI) should have caught most issues. A current weak spot in our testing is the QGIS plugin, so a manual test plan is in place. Start with running the automated task to see if it can be correctly installed.

# This test might give a fatal error on the first run, this is most likely a timing issue.
# Try to run it again when that happens.
pixi run test-ribasim-qgis-ui

Then follow the instructions as described in the QGIS manual test plan.

2.8 Announce release

Announce the release in appropriate channels. Include a link to the release notes and assets, which is whatever this resolves to at that time. Also include a link to the documentation.