Release process

What is a release

The imod_coupler repository contains multiple components, at the time of this writing the pre-processing package primod and imod_coupler itself. The components are currently only guaranteed to work together if they are built at the same time. Therefore we release iMOD Coupler as a collection of all the components at once. For maximum interoperability it is suggested to only release all components together, and not individually.

For these releases we use Calender Versioning, which makes it clear in which month the release was made.

Release steps

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

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.

Update version numbers of the components as needed

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.

The components are only guaranteed to work together if they are built at the same time. To clearly communicate this, component versions need to have synchronized version numbers. This means that both version numbers should be updated even if only one component has been changed.

Update the version numbers in the repository to the new version number. Update the following two locations:

  • imod_coupler/__init__.py
  • pre-processing/primod/__init__.py

Now submit a pull request which updates the version numbers of the components as needed.

  • Create a new branch and switch to it, for example: git switch --create new-release.
  • Create a new commit with the updated version number
  • Push to remote
  • Create a Pull Request
  • Merge the Pull Request into main

Create a new release

Create a new tag like v2023.1.0 by prepending v to the calver version number.

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’ll probably want to curate that by rearranging the most important changes for users to the top in the form of Keep a Changelog. The possibly long list of generated release notes can put below an “All changes” collapsed item as such:

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

# Put Github flavored markdown here

</details>

Release primod on PyPI

To be able to do pip install primod , primod needs to be released on the Python Package Index. First, make sure that you have a PyPI account. Then create a new API token and store it in a secure location.

Run the following to start the process:

pixi run publish-primod

Announce release

Announce the release in appropriate channels.