How to make a release

These steps are intended as a short guide on how to make a release. Right now, all releases are made by the main maintainer, but I wanted to document the process for the future.

Preliminaries

1. Pull recent changes in the develop branch.
2. Check that all the tests pass and the docs are generated correctly.

Creating a release branch

1. Check the version of the release. Normally, the develop branch should already have a version X.Y.Z.devN in __init__.py, and the release version should be X.Y.Z. However it is important to check if there have been breaking changes since the last released version and the major number has not been changed. In that case, we should increase the major version and reset the minor version at this point. Do NOT remove the .devN extension yet.
2. Create a release branch using Gitflow:

   git flow release start X.Y.Z

3. Update the version in __init__.py to X.Y.Z (remove the .devN extension).
4. Push the branch to the remote und wait for all tests to pass.
5. Finish the release branch:

   git flow release finish X.Y.Z

   This step updates master and develop locally, and removes the release branch.
6. Push develop, master and tags, and wait for the tests to pass.

Publishing the tag

1. Make a release of the tag corresponding to the generated version.
   • Ensure that the autogenerated changelog is complete and readable for users. Feel free to remove pull request that have no user-facing consequences, and to add user-facing changes not done via pull requests (which should be 0).
   • Check the box to make a new discussion in the Announcements section.

Updating develop version

1. Change the version in __init__.py in the develop branch. Increase minor version and add .devN suffix.
2. Change the version displayed in the web for the stable branch in docs/_static/switcher.json.