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: .. code-block:: console gh release create --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.