Skip to content

Making a release

This list outlines the manual steps needed to make a new release of the benefits app.

A release is made by merging changes into the prod branch, which kicks off a deployment to the production environment. More details on the deployment steps can be found under Workflows.

The list of releases can be found on the repository Releases page on GitHub.

Start a new Release on Github

0. Decide on the new version number

A new release implies a new version.

benefits uses the CalVer versioning scheme, where version numbers look like: YYYY.0M.R

  • YYYY is the 4-digit year of the release; e.g. 2021, 2022
  • 0M is the 2-digit, 0-padded month of the release; e.g. 02 is February, 12 is December.
  • R is the 1-based release counter for the given year and month; e.g. 1 for the first release of the month, 2 for the second, and so on.

1. Prepare release in a branch

Typically changes for a release will move from dev, to test, to prod. This assumes dev is in a state that it can be deployed without disruption. (This is called a Regular release.)

If dev or test contain in-progress work that is not ready for production, and a hotfix is needed in production, a separate process to test the changes before deploying to prod must be undertaken. (This is called a Hotfix release.)

As implied in the previous step, all releases follow the same version number format.

The following diagram shows how a release should propagate to prod under different circumstances:

graph LR
    A(Release branch) --> B{Are dev and test ready to deploy?};
    B -->|Yes| C(dev);
    C --> D(test);
    D --> E(prod);
    B -->|No| E;

By convention the release branch is called release/YYYY.0M.R using the upcoming version number.

2. Bump the application version number

The app code maintains a version number in benefits/, used by the instrumentation and logging systems.

This version number must be updated to match the new version in the same format: YYYY.0M.R

3. Open a PR

Initially from the release branch to the target environment branch, following the merge sequence in the diagram above.

4. Merge the PR

After checks pass and review approval is given, merge the PR to kick off the deployment.

Repeat steps 3 and 4 for each deployment environment target, again following the merge sequence in the diagram above.

5. Tag the release

Once the deploy has completed to prod, the version can be tagged and pushed to GitHub.

From a local terminal:

git fetch

git checkout prod

git reset --hard origin/prod

git tag -a YYYY.0M.R

Git will open your default text editor and prompt you for the tag annotation. For the tag annotation, use the title of the release-tagged Issue that kicked off the release. Finally, after closing the text editor:

git push origin YYYY.0M.R

6. Generate release notes

Also add a written description, and include screenshots/animations of new/updated pages/workflows.