# Branching and Merging Guidelines
Concerning branching and merging, our team decided on using a variation of the Gitflow workflow. This page describes its background and impact for contributors.
# Gitflow Workflow
As a contributor you would probably only be confronted with the topics in the following "Daily Development & Feature Branches" sections. The other parts are taken care of by the Storefront UI core team.
# Daily Development & Feature Branches
Gitflow defines two major, long-living branches:
Daily development takes place in feature branches which are derived from
develop and, after QA, merged back into
We apply the strict variant in which the only commits allowed to
develop are merge commits. So everything that should land in
develop needs to go through a feature branch.
In daily development
master is never touched; neither branched from nor merged into.
As a convention, we prepend every branch that doesn't fall into one of the following categories with the GitHub issue number this branch relates to, like so:
#1234-sftoggle. See also our Github Guidelines.
In order to release a specific repo state, with a version number and tag and all, a release branch can be created. It is also derived from
develop but merged into
At the same time a version tag is created on
master, pointing to the merge commit.
The release branch can stay open as long as that specific version line is supported. It is needed for hotfixes (see below).
Note: Keeping release branches open is actually a deviation from the original gitflow workflow which is made for only one actively supported release. There, a release branch is closed the moment it is merged into
master. With the need to maintain multiple version lines, the way proposed here is an appropriate variation.
Following the original gitflow naming convention for release branches, we prepend release branches with
release/ followed by the release version, e.g.
release/1.2.0. A common tag convention is the
v prefix as in
If the situation arrives where urgent bugs need to be fixed in all affected and still supported release versions, hotfix branches are created. Those are the only branches created from
master and must be merged back into
develop and all supported
Those commits are normally small and don't create (many) merge conflicts. But sometimes hotfix changes require extra work in order to backport them into earlier releases. All this work has to go through QA, i.e. PRs, so no new issues are introduced into one or more releases.
Such branches are prefixed with
hotfix/ plus the new version number, e.g.
Theoretically (but not necessarily), to minimize confusion in the git history, it is advised to create a branch for each supported release branch, branched away from the original hotfix branch (which is targeted towards the most recent release) and name those branches according to the last version in those release branches.
(Example: Create a hotfix branch from
master towards the most recent version, e.g.
hotfix/2.2.1, merge it into
develop and create new hotfix branches from that branch for older releases, e.g.
hotfix/2.0.9, and merge them into those.)
Also, new tags are created for all fixed release branches.
While committing often on a feature branch is accepted and even appreciated for the sake of transparent code reviews, our team agreed on using squash commits for merges into the
# Conventional Commits
Storefront UI uses Conventional Commits, i.e. our commit message headlines apply to a certain format that allows for automatic changelog generation and makes commits easier to reason about because of the conventions. Our commits are checked against these rules as a pre-commit hook. Currently we use the "config-conventional" ruleset. It includes the following commit types you can choose from to prepend your commit with:
So valid commit headlines would include the following:
feat: add global isMobile listener
docs: update branching guidelines
test: overhaul provide-inject pattern
In order to narrow your commit down to a certain component or aspect, you can also specify the commit scope like so:
feat(button): add longpress tooltip
refactor(organisms): reorder imports
style(toggle): smoothen animation