Branches

This page will introduce the naming conventions for the different types of branches and highlight their specific use cases.

Main branch

The main branch is the singular and first branch existing on a new repository. It is used to represent the current state of the project, therefore it is most important to keep it in a stable state.

Danger

Direct work on the main branch is forbidden!

The main branch is used to track the latest release version of the project. A release is a traceable version of the project, and therefore the main branch can be seen as an overview of the different releases, as seen below:

%%{init: { 'gitGraph': {'showCommitLabel': false}} }%% gitGraph commit commit tag: "v1.0.0" commit tag: "v2.0.0" commit tag: "v2.2.0" commit tag: "v3.0.0"

Note that the commits in the figure above are the result of merge operations from release branches.

Hint

We use Semantic Versioning to determine the version number of each release.

Release branches

Release branches serve as a staging area for the integration of new features and fixes.

A release branch has the prefix release/ followed by the future release version that will be published to main when the work on all features has been completed excluding the patch version: release/v<major>.<minor>.x. For example, the branch release/v2.0.x contains all the patches belonging to major version 2 and minor version 0.

While the state of the software on a release branch does not necessarily have to be stable, they are not intended to be worked on directly. For this reason, feature and bugfix branches are introduced.

Ready for release

Once all the features planned for the release have been implemented and the release branch is ready, a Pull Request (PR) can be started to merge it into main.

Warning

A Pull Request (PR) must be performed to merge a release into main.

%%{init: { 'gitGraph': {'showCommitLabel': false}} }%% gitGraph commit commit tag: "v1.0.0" branch release/v2.0.x commit commit commit checkout main merge release/v2.0.x tag: "v2.0.0"

In an ideal world, the work on release v3.0.0 can begin after release v2.0.0 is completed and the new tag can be used as a branching point for the next release branch. In practice, shifting priorities and complexities will result in the need for parallel release branches as shown below.

%%{init: { 'gitGraph': {'showCommitLabel': false}} }%% gitGraph commit commit tag: "v1.0.0" branch release/v2.0.x commit commit branch release/v3.0.x commit checkout release/v2.0.x commit checkout main merge release/v2.0.x tag: "v2.0.0" checkout release/v3.0.x merge release/v2.0.x commit commit checkout main merge release/v3.0.x tag: "v3.0.0"

Important

Do not delete the release/ branches after these have been merged to main! You can keep using them for future patches or bugfixes, or as reference for future development.

Feature branches

Feature branches are created to implement or change a distinct feature. There are no special restrictions on feature branches and work can be directly commited to a feature branch.

Feature branch naming convention is a prefix plus the name of the feature to be worked on, like feature/multiuser_support or feature/client_rework.

%%{init: { 'gitGraph': {'showCommitLabel': false}} }%% gitGraph commit tag: "v1.0.0" branch release/v2.0.x branch feature/multiuser_support commit checkout release/v2.0.x branch feature/client_rework commit checkout feature/multiuser_support commit checkout feature/client_rework commit checkout release/v2.0.x merge feature/multiuser_support merge feature/client_rework checkout main merge release/v2.0.x tag: "v2.0.0"

Warning

A Pull Request (PR) must be performed to merge a feature into a release.

Bugfix branches

Bugfix branches are indicated by the bugfix/<name> naming sheme. They are used to solve identified issues in already existing releases. To make these fixes available for already published releases, a special release branch can be created. For example branch release/v4.0.x would serve as the way to release bugfix versions of release v4.0.0. This allows for a cleaner main branch and the possibility to resolve issues in old releases without affecting the work for future software versions.

%%{init: { 'gitGraph': {'showCommitLabel': false}} }%% gitGraph commit tag: "v3.0.0" branch release/v4.0.x commit checkout main merge release/v4.0.x tag: "v4.0.0" branch release/v5.0.x commit checkout main checkout release/v4.0.x branch bugfix/error_condition commit commit checkout release/v4.0.x merge bugfix/error_condition checkout main merge release/v4.0.x tag: "v4.0.1" checkout release/v5.0.x commit checkout main merge release/v5.0.x tag: "v5.0.0"

Warning

A Pull Request (PR) must be performed to merge a bugfix into a release.