Release Workflow

Schedule

A new version of bluemira is tagged every 6 weeks; marking the end of a development cycle. When a new release is due, a scheduled GitHub Actions workflow opens an issue to create a release. A new release is then generated by the team using a manually triggered GitHub Actions workflow.

When a release is generated, a pull request is automatically opened to merge the develop_dependencies branch into develop.

Creating a Release

Releases are created using a GitHub actions workflow. A maintainer triggers the workflow (specifying a version number), which checks out main, performs a fast-forward merge with develop, and pushes the changes to main. A release is then generated from the HEAD of main, using the GitHub CLI.

The release is made this way in order to use a fast-forward merge. GitHub does not allow fast-forward merges through pull requests. It is important for the histories of main and develop to be consistent, otherwise there may be conflicts between the branches in the future. It also means release tags are locatable in the histories of both branches.

In the unlikely event that main and develop’s histories diverge and a fast-forward merge is not possible, the release pipeline will fail. The maintainers must resolve these conflicts manually.

Versioning

Bluemira’s versioning strategy follows the scheme laid out in PEP440, but always uses 3 version numbers (major, minor, patch) as in semantic versioning. As per the PEP, the version can optionally contain a suffix specifying a pre-release (.(a|b|rc)N), post release (.postN), or development release (.devN) number.

Dependency Updates

After a release is created, a pull request is automatically created to merge the develop_dependencies branch into develop. This is a reminder to update our dependencies for the next development cycle.

In order for the develop_dependencies and develop branch to not diverge, the pull request must be merged using GitHub’s ‘Merge commit’ option. GitHub does not provide a way to perform fast-forward merges, which would be the ideal case. Using a merge commit is the next best thing we can do to prevent the branches from diverging.

This does present a risk, as pushing the wrong merge button could result in having to revert, and re-do, the merge. However, this was seen as a better option than implementing a fast-forward merge action on GitHub, which would mean performing our own validation for when the PR can be merged, and by whom.

Release Notes

Release notes are auto-generated by the GitHub CLI call that creates the release, using the generate-notes flag:

gh release create <tag> --generate-notes

This generates notes from pull requests that were merged in the release period.

In the future, it may be necessary to have more user-centric release notes. For this, the use of towncrier has been discussed.