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 "Release" pull request will be started.

Hotfix Releases

There is a separate GitHub Action to manage hotfix releases. This action monitors all branches matching the pattern "hotfix*" (i.e. start 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. First we need to create branch called "hotfix" from our lastest release tag. And create another branch (could call it whatever), also from our latest release tag and apply the the hotfix changes to this branch. And then create a pull request from the 2nd branch to the "hotfix" branch, and it should only be merged to "hotfix" branch. When we merged the 2nd branch to the "hotfix" branch, the hotfix release management will be triggered and a hotfix release pull request will be created automatically. Merge the hotfix release pull request to get a new release tag for hotfix.

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. It would be ideal to have one merge per issue. If this is tricky, consider coordinating development work (and deploys to DEV) on the dev branch and then squashing commits when desired (or just live with a somewhat messy CHANGELOG -- it's not the end of the world).
• 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)".

Process for Doing a PROD deployment from a Release Tag

• Check the latest release tag in the TEST deployment, and make sure we will do the same release deployment for PROD
• Go through the PROD release checklist in confluence: https://apps.nrs.gov.bc.ca/int/confluence/pages/viewpage.action?pageId=171773590, create a new one each time from the template
• Check AWS PROD Cognito Dev clients, to see if there are any manually added dev urls, write them down (we need to manually add them back after the new release)
• Update PROD protection rules to allow deploy from the release tag
  • Go to repo settings -> Enviornment -> Prod
  • Under the "Deployment branches" section, add the release tag
• Run Prod deployment from that tag
• Verify Prod deployment is successful, check our site is reachable , API is working
• Go to AWS PROD Cognito Dev clients, and manually add dev urls (non-fixed urls we write down in step 3) back
• Remove the release tag from the Prod protection rules
• For admin management api, currently after deploying frontend will see CORS issue described in the previously ticket #449, can be solved by manually redeploy the admin management Api Gateway.