Release

Overview of Semantic Versioning

Semantic Versioning is a set of rules and grammar for version numbers and how they should be assigned and incremented.

The rules are designed around a numbering system that follows an X.Y.Z pattern with additional suffixes if needed. The X is the major version number, the Y is the minor version number and the Z is the patch version number. The rules define when these can be incremented and that the released package should not be modified without modifying the version number and releasing a new version.

How this Template follows Versioning

This template follows this branching strategy for the 2 important branches (develop and main). The main branch contains the most recently released stable code, this branch will typically only be updated by release-* branches that have been cut off of develop and are fully tested to ensure quality. The template uses git-mkver to automatically determine the next version number with conventional commits when release or patch branches are created.

Once the release-* branch has been cut off of develop, the version number is updated in the README file (this will be the Major or Minor release number) and a PR will be created into the main branch that contains the list of code changes since the last release branch.

After the release-* branch is merged into main, the newest commit in main will be tagged with the release number vX.Y.Z and a release will be created on GitHub with the list of code changes since the last release branch.

Patch branches can also be cut off of main to patch the most recent release, these branches should only contain bugfixes and will increment the patch version number on main when they are merged.

Github Actions and Apps

Github Actions and Applications are used in this template to help automate this process and ensure it is followed correctly. There are Automated Actions and Applications that run to ensure the PRs are written and merged with the proper Titles and Commit Message with the correct merge strategy (All Feature Branches merged to develop should be SQUASHED).

We use Bulldozer to Automatically merge PRs into develop once all checks have passed and there is a comment saying !merge. This could also be limited to once 1 or 2 approvals are given to the PR by requiring that on the develop branch.

There are Semi-Automated Actions to Create the release-* and patch-* branches when they are desired by the repo administrators.

Release Process

Cutting

When it is decided a new release is desired, the first step is to cut a release-* branch off of develop. This is Semi-Automated with a the release-cut` GitHub Action. This should:

• Determine next release version number (major or minor increment)
• Create release branch off of develop
• Create PR into main with list of changes since last release-* branch

Merging

Merging the release-* branch PR is a manual step that the repo Administrators will need to do. These merges should be done with the "standard" merging process so the history is maintained.

Tagging/Release Notes

After the release-* branch has been merged to main, an Automated GitHub Action should run to tag the commit with the newest version number and create a release on GitHub with the Release Notes containing the list of changes since the last release.

How to

Cut Minor Release

This will be the typical release and it is the easiest to do. Minor releases should be created by the release-cut Github Action automatically once a feature/ or feat/ branch has been merged automatically by Bulldozer (should be squash and merged with feature:* or feat:*` commit message).

To create the release:

1. Navigate to the `Actions tab
2. Select the release-cut Action
3. Press the Run Workflow Button and ensure develop is selected then press Run

If there are errors in creating the release branch, you likely have not merged any new feature branches since the last release.

Cut Major Release

To cut a Major release, the repo administrator will need to be a little more involved. They will need to SQUASH and merge a PR into develop manually and include the commit message footer: BREAKING CHANGE. This should then cause the Release-Cut Action to create a Major release once it is triggered (same process as above).

Patch main (newest release)

If you notice a bug that needs to be patched on the most recent release, this will be the easiest to do as there will be the fewest conflicts possible. The Patch-Cut GitHub Action will automatically create the patch-* branch off of branch you select (must be main for newest release) and update the README for the patch. The action will also create the PR for patching the branch automatically.

Once the patch-* PR is manually merged (without squashing), the Automated GitHub Actions should take over to Tag and Create a GitHub release with release notes that contain the commit messages from the patch branch.

Patch older release

Patching an older release uses the same Patch-Cut GitHub Action, but you will need to select the release-* branch that you want to patch to. The action should create the PR for patching the release-* branch automatically after the patch-* branch is created. Once the PR has been approved you can merge (without squashing) and the Automated GitHub Actions should take over to Tag and Create a GitHub release with release notes.