Creating a Release

What is a Release

A "Release" is a set of artifacts that correspond to a version of the codebase that is a candidate for deployment. A "Release" is not an action! "Creating a release" is an action, as is "Doing a release" or "Deploying a release to TEST" or "Deploying a release to PROD". The simple action of "Creating a release" does not affect any environments (need to trigger a deployment in order for that to happen.

A release consists of:

1. Assignment of a release version using semantic versioning, based on the fixes and features included in the release (and using the previous release version as a baseline).
2. An up-to-date CHANGELOG document in the repository.
3. Creation of an actual "release" artifact on GitHub (an entry on the Releases page on GitHub). This includes a description with a changelog as well as a zip/tar archive of the source base.
4. A GitHub tag corresponding to the release version.

How to Create a Release

We use Release Please to create releases. This is a GitHub action that monitors the changes to the repository and maintains a Pull Request. The Pull Request that is maintained by Release Please keeps a tidy list of the changes since the last release.

To create a release: Merge the Release Please pull request to main.

After Creating a Release

• The Release Please pull request will be merged and the GitHub action will have created all the artifacts.
• When the next pull request is merged to main a new "Request" pull request will be created.

Hotfix Releases

There is a separate GitHub Action to manage hotfix releases. This action monitors all branches matching the pattern "*hotfix" (i.e. ending with "hotfix"). When working on a hotfix, using this naming convention will allow you to get the Release Please functionality the same as in the main branch.

This means that during a hotfix process, there will be two Release Please pull requests. It's important not to mix them up. The hotfix pull request should only be merged to the hotfix branch.

It's possible that the version created by the hotfix release will clash with the version created by a main release. The only technical problem this situation could create is that the Git tag might clash. The hotfix will typically only be bumping the latest PROD release by one minor version, so it is unlikely that this will happen, but watch out for it. (If we create a release on the main branch that also bumps by one minor version, the version number will be the same).

After the hotfix is applied, the hotfix branch should be merged back to the main branch (so the hotfix is not lost in the next release). The minor version bump from the hotfix will naturally be included in the new version of the main branch in this case.

Notes on Conventional Commits

• The version bumping and CHANGELOG management only works properly if the team follows the Conventional Commits standard.
• Each commit to the main branch will end up in the CHANGELOG. It's fine to commit as many times as you like to your local branch, but when merging to main, please squash commits and provide a useful commit message that follows the standard.
• To encourage the use of conventional commits, the default message for a PR merge will come from the PR name, and there is a check in the pipeline that enforces this. You can still mess it up manually at merge time, but hopefully this helps.
• If you put the issue number in the PR name, hopefully at the beginning, it appears in the CHANGELOG as a link back to the GitHub issue. The same happens if you put the pull request number in the PR name. GitHub adds the PR number at the end of the merge commit automatically, but the issue number needs to be added manually. This makes it really easy to navigate from the CHANGELOG back to the individual issues or to search for them in ZenHub. An example of a useful commit message: "fix: #567 Add home link to nav bar (#579)".