Releasing procedure

The codebase development is done using the Git-flow branching pattern¹.

Use a Git extension

There are few extensions that allow to automatize the overhead of sticking to the branching model by hand, i.e. by using Git vanilla commands. Since trunk based development has become in the software landscape more appealing, most Git extension to implement Git-flow pattern have decreased maintenance and many froze. However, in simple scenarios, like manual usage in the terminal, any extension should work as expected. You can check-out the AVH edition (which has been archived in June 2023) or the CJS Edition which is still (rarely) active. Both are successors of the original implementation by Vincent Driessen, who invented the model in first place.

When the code is ready to be published, a release branch shall be created and the finalization steps should be carried out on it. Closing the branch means to merge it into main, which will be tagged and contain the released version, and merge it back to develop, which in principle might have continue development.

Don't forget to update the version string

In the codebase there is a global HYBRID_codebase_version variable, which contains the version label. This should be bumped on the release branch, i.e. when it is clear which will be the following version number. Analogously, it should be bumped into a dirty state² on develop as soon as the release is closed.

Release checklist

• Create the release branch from develop and switch to it.

  If you are doing a hot-fix, an extra step is needed here!

  For hot-fixes, you will branch off main and the repository will be in a stable state. Hence, you need to immediately bump the version to the hot-fix one adding e.g. a -start suffix. Before closing the branch you will remove such a suffix.

• Make sure everything is ready to go (e.g. check copyright statements including in documentation).

• Change the Unreleased box in the CHANGELOG file to a new release section by
  • adding the new section title;
  • changing the type of box;
  • adding release date and link to changes from previous version.
• Bump version number global variable in main script to a stable state.
• Update CITATION.cff file w.r.t version number, release date and possibly authors information
• Close the release branch in the following sense:
  • merge it into the main branch;
  • switch to main and tag the last commit;
  • switch to develop and merge the main back into it³.
• Publish the new release by pushing the changes and the new tag on main.
• From main build and deploy the documentation.
• From develop bump version number global variable in main script to an unstable state and prepare a !!! work-in-progress "Unreleased" box in the CHANGELOG file.

Create the release branchClose the release branchPublish new release

# Git-flow extension
git flow release start 1.2.0

# Vanilla Git commands
git switch -c release/1.2.0 develop

# Vanilla Git commands
git switch main
git merge --no-ff release/1.2.0
git tag -a Hybrid-handler-1.2.0
git switch develop
git merge --no-ff main
git branch -d release/1.2.0

# Git-flow extension
git flow release finish 1.2.0 # (1)!
git switch develop
git merge main

1. Using Git-flow extension in this case is discouraged because we want to merge main into develop to have the new tag done on main reachable from develop via git-describe. However, if you still want to use Git-flow, you need to run git switch develop && git merge main after having closed the release branch. Furthermore, the git flow release finish command assumes that the tag prefix Hybrid-handler has been set at initialization time in the Git-flow extension!

# Only vanilla Git commands
git push origin main
git push origin develop
git push origin --tags
git push origin :release/1.2.0  # if pushed

---

1. Alessandro has offered a trilogy of talks about Git and these are available on his GitHub profile AxelKrypton. The second part of the last talk is devoted to introduce and explain this branching pattern in detail. ↩

2. The version variable should make clear whether the codebase is in a stable state or not. Usually a suffix like -next or -unreleased is added to the last stable version name immediately after the release (in a dedicated commit), such that the main script will report the dirty state when run with the --version option. ↩

3. This might lead to conflicts if the codebase has evolved on the develop branch. Please note as well that merging the release branch into develop would be equivalent in terms of code changes, but the tagged commit would not be reachable from the develop branch when using git-describe. ↩