Version control

Branching strategy

Branching allows teams of developers to easily collaborate inside one central code-base. When a developer creates a branch, the version control system creates a copy of the code-base at that point in time. Changes to the branch don’t affect other developers on the team.

This is a good thing, obviously, because features under development can create instability, which would be highly disruptive if all work was happening on the main code line. But branches need not live in solitary confinement. Developers can easily pull down changes from other developers to collaborate on features and ensure their private branch doesn’t diverge too far from the main.

A uniform and consistent branching strategy is important for a team to be able to collaborate effectively. We follow a pseudo GitHub Flow branching strategy with some slight modifications.

Key concepts

Always branch off the default branch AKA, main.
The main branch is always considered stable and up to date.
Development work occurs in temporary working branches.
Branch names follow a convention.
Code is integrated into main via merge requests.

The image above shows the branching model, it’s remarkably simple, this is by design. Later we will build on this to include mandatory quality gates and as well as deployment strategies.

If there is lots of activity on the project it’s a good idea to merge main into your working branch daily. This will keep it up to date and avoid conflicts later on.

Branch naming conventions

It’s important to name branches consistently so that it’s easy to identify the purpose of a branch. We use the following naming conventions:

Permanent branches

The only permanent branch is main. This branch is always considered deployable and stable. All other branches are temporary and should be removed after merging into main.

Temporary working branches

Upon completing work on any temporary branch, the branch should be deleted.

Branch names are always in lowercase. Temporary working branches should be prefixed with a relevant category, these are described below. The category is followed by a brief description, for readability use dashes between words. The category and description are separated with a ”/” mark.

Feature

Should be used when adding, refactoring or removing a feature. Usually, a sizable piece of work. Example: feature/search-page

Bugfix

Should be used when fixing a bug. Example: bugfix/fix-login-redirect

Support

Should be for all support changes requested by a client. Example: support/JIRA-123

Hotfix

Should be for fixing bugs in production releases that need to be fixed quickly. Example: hotfix/fix-login-redirect

Deploy branches

These can also be considered release branches. You do not need to create these manually, they are created by triggering a deployment in the GitLab CI. Deploy branches are automatically prefixed with deploy/. There are two categories of deploy branches:

Working deploy branches

These are temporary and are used to expose working code within Matrix. This is handy for testing and demoing features before they are merged into main.

An example might be deploy/feature-search-filter.

Permanent deploy branches

These are permanent and contain code for different environments.

An example might be deploy/staging.

While there will be a deploy/production permanent branch, it’s better to run the production code from automatically created tags. You can learn more about deployment here.