git-branching-strategy.md

Git branching strategy

This document describes the Git branching strategy that must be followed for the development.

The CI/CD pipelines and the automatic deployments are tightly related to this Git strategy, but they are described in another document. The current document only describes the Git branching strategy, not the CI/CD process.

Description

The Git branching strategy described in this document is custom-made, but is greatly inspired by existing strategies, like GitHub Flow, Trunk Based Development, or OneFlow.

The strategy was created to meet the following objectives:

• Simple.
• Fit our current development process.
• Allow to deploy different versions of the code on different environments.
• Limit the number of branches with active work, to prevent managing too many unsynchronized branches.
• Limit merges between branches to prevent a "merge hell".
• Have a clear "hot fix" strategy.
• Allow release versions, and an easy way to "rollback".

Developing new features

Development of new features is done on the main branch. See (A) in the graph below.

This branch always contain the most up-to-date version of the code. While this branch is not directly used in production (see the CI/CD process for more details), it must always contain a working version of the site, with the latest fixes and developed features.

When developing a new feature, a feature branch is created from main. A feature branch is generally named <TICKET>-<DESCRIPTION> where <TICKET> is a related ticket number (ex: a Jira or Basecamp ticket) and <DESCRIPTION> is a short description of the feature. See (B) in the graph below for an example.

The feature branches must be short-lived (no more than a few days) and must be limited in the size of the feature they introduce. Large features should be split into smaller features. We want to prevent having long-lasting branches that become difficult to merge.

Merging a feature branch into main must pass through the Pull Request process. Always use "Squash and Merge" when merging.

Creating a release

A "release" is a version of the code that is considered ready for production. In this Git strategy, a new release is always for a version containing new features. For a version containing only bug fixes, see the "Hot fixes" section below.

When a release is ready to be made, two steps must be taken:

1. On the commit on main that you want to release, add a release tag.

   A release tag serves to mark a commit containing a released version. A release tag's name is the release's version number <MAJOR>.<MINOR>.<PATCH> preceded by v. Example: v2.1.0. See (C) in the graph below.

2. From the same commit, create a new release branch.

   A release branch allows to eventually implement hot fixes in case a bug is discovered in this release (see the "Hot fixes" section below). The release branch's name is release/<MAJOR>.<MINOR>.x. Note that <PATCH> is replaced by x. Example: release/2.1.x. See (D) in the graph below.

It's possible to create a release from a previous commit if we don't want the latest features of main to be released yet. See (E) in the graph below.

Development of new features continue on the main branch after the released commit.

When another release from the main branch is ready to be created, a new release tag and release branch are created on the commit to release. See (F) in the graph below for an example for version 2.2.0.

Release version number

The version number for the release is determined by the developer, based on the previous release's version number. It is globally inspired by the semver format <MAJOR>.<MINOR>.<PATCH>.

• The <PATCH> is increased when introducing fixes that don’t introduce or change existing features. In this Git strategy, this number is increased only for hot fixes. A new release should always introduce new features, so it should have a <PATCH> number of 0.
• The <MINOR> is increased when introducing a new feature, or changing an existing feature.
• The <MAJOR> is increased when introducing a major redesign that affects most of the site.

Notes about release branches:

• No commits should be allowed on a release branch, except for "hot fixes" (see the "Hot fixes" section below). In particular, no new feature should be developed on a release branch.
• If a release branch never gets any "hot fix", it will simply stay an "empty" branch starting from a commit on main.
• The name of the release branch always ends with .x, it doesn't include the <PATCH> number.
• "Previous" release branches and release tags are not deleted when releasing a new version. They allow for easy rollback.

Hot fixes

A "hot fix" is a correction of a bug on a released version. This section assumes the following about the fix:

• It's a small (bug) fix, not a new feature. New features should be developed only on the main branch.
• It's to be applied on a previous release. If it's a fix to apply only on the latest commit of main, develop it like a feature (see "Developing new features" above).

Developing a hot fix is similar to developing a new feature and creating a release, except it's done from the release branch instead of from main.

From the release branch of the version to fix, create a new branch and develop your fix in it. Once ready, create a Pull Request to merge it back into the release branch. It's possible to create multiple branches if multiple fixes are required. See (G) in the graph below.

Once all fixes are approved and merged, create a new version tag on the branch's latest commit. The version number should only have it's <PATCH> version number incremented by one. See (H) in the graph below.

Apply the fix to main

Don't forget to also fix main (if applicable) so there is no regression in the next release.

If the fix can be applied exactly the same way, you can merge the release branch into main. Alternatively, you can cherry-pick the commits.

If main evolved in a way that the fix cannot be applied the same way, develop the fix like a feature (see "Developing new features" above).

About v1

The following applies only during the transition period where v1 is still the production version and v2 is being developed.

For the development of a new feature or a hot fix on v1:

1. Create a branch from the demo branch.
2. Develop your code and create a pull request (to merge into demo). Once merged, the staging server will automatically pull from the demo branch.
3. Once approved for production deployment, merge only the new commit(s) (ex: with cherry-picking) into the release/v1.x branch.
4. This branch will then have to be manually pulled on the production server.