Release Strategy - bcgov/SIMS GitHub Wiki

The release strategy follows the below workflow.

To edit the workflow, please go to FigJam or contact the designer on the project.

Versioning

We try to follow the semantic version for the first part of the version (e.g. v1.0.0) and we opened an exception for the way that the build is currently appended to the semantic version using the -build_number, for instance, v1.0.0**-149**. So, in general, the v1.0.0 follows the same stated on the https://semver.org, where:

MAJOR version when you make incompatible API changes.
MINOR version when you add functionality in a backward-compatible manner.
PATCH version when you make backward-compatible bug fixes.

Branches

main (permanent)

Contains all the history of the developed tickets and from where developers create new branches to work on tickets. Developers must create pull requests once the work is done to have it merged into main. The pull requests are merged using the Squash and merge option. Every time that a pull request is merged it will generate a build with a tag, for instance, main-123 and this will be automatically deployed to the DEV environment.

release/hotfix (temporary)

Temporary branches created from main branch, prefixed with release/ or hotfix/ to allow the stabilization and manual tests to be executed and signed off by the business. They are intended to be short-lived. More than one release branch can exist at a given time but it is not desirable. The developers should create branches to work in any release/hotfix last-minute change or fix. Once the work is done it should be merged into the release/hotfix branch through a pull request and using the Squash and merge option. Once the release/hotfix is deployed it should be merged back to the main branch using the Create merge and commit option. If any conflict happens the suggested approach is to create an intermediate branch for the conflict resolution and then merge it back to the main.

Cherry picking

In the event that temporary branches (e.g. release/hotfix) are under development/stabilization and some feature/commit must be moved between them, the expectation is that a new branch should be created from the target branch and the git cherry-pick must be executed, to then allow a pull request to be created, reviewed and merged into the target branch using Create merge and commit.

Step 1: Create a new branch from target branch where your cherry picked commit must go into. e.g. If you need to cherry-pick a commit from main branch into release branch, create a new branch from release branch.

Step 2: Go to VS Code IDE and find the commit to cherry-pick and right click on the commit and then execute the cherry pick. Click on source control on the left side and expand the branches accordion to find the commit.

To find commit and right click:

To execute cherry-pick

Step 3: Once step 2 is done, the commit will become the part of new branch. So just push the commit to origin.

How to start a release/hotfix

Decide which tag from the main branch will be used to create the release/hotfix.
Execute the GitHub action Release - Create Branch to create the new branch.

Execute the GutHub action Release - Build All to generate the tag and the release build.

Once the build is done, secrets can be deployed as needed to DEV/TEST/PROD if needed else skip to the next step (step 5).

Once the build and secret deployment(only if needed) is done it can be deployed as needed to DEV/TEST/PROD.

Every new pull request merged into the release/hotfix branches will generate a new tag that can be deployed.

How to create a release (release or hotfix)

To provide additional info about the release, we can create a new "Release" on GitHub to point to the release tag and add the tickets related to the release.

Once the version that will be deployed to TEST and other pre-prod environments is ready, we can create a new Release as below.

Navigate to the Releases page and click on "Draft new release".
Search for the release tag, as shown below.
Generate the release content and publish it, as shown below (the release can be edited or deleted as many times as needed).

Adjusting the release for new changes on the release branch.

If the release branch receives more changes and needs to be deployed again, the release previously created can be changed to point to the new tag and also have its content updated to reflect the new ticket added.

Merge a release/hotfix back to the main branch

Please find below an example of how to merge the release/hotfix back to the main branch. Assuming that there is no merge conflicts a PR can be created directly from the release/hotfix into main. In case there are conflicts to be resolved, an intermediate branch can be create, as shown below.

Get the latest changes from the release/hotfix. For the below example we will be using release/v1.0.0.

git checkout release/v1.0.0
git pull

Switch to the main branch, get the latest, and create a new branch to merge the release/hotfix.

git checkout main
git pull
git checkout -b release-v1.0.0-to-main-merge
git merge release/v1.0.0

Resolve any merge conflicts
Request the approvals for the pull request.
Merge using the Create merge and commit as mentioned also release/hotfix section.
Delete the release/hotfix branch.

Database Migrations

For every release applying DB migrations, a rollback plan will be needed. To know the exact differences between production and release versions, the below folders from both tags can be compared.

GitHub URL with migrations.

https://github.com/bcgov/SIMS/tree/release_or_hotfix_tag/sources/packages/backend/apps/db-migrations/src/migrations

For instance, the comparison between the below versions will result in the below image, where the highlighted green area represents the files added between the two versions.

https://github.com/bcgov/SIMS/tree/v1.0.1-253/sources/packages/backend/apps/db-migrations/src/migrations and https://github.com/bcgov/SIMS/tree/v1.1.0-318/sources/packages/backend/apps/db-migrations/src/migrations