Branching guidelines

Main branches

• main
• develop

The HEAD of origin/main always reflects a production-ready state

The HEAD of origin/develop always reflects a state with the latest delivered development changes for the next release, the “integration branch”.

When the source code in the develop branch reaches a stable point and is ready to be released, all of the changes should be merged back into master and tagged with a release number.

Only merge commits should be performed on these branches. Everything should theoretically be performed in other branches, including bug fixes in hotfix branches.

By definition, each time when changes are merged back into main, it is a new production release. This should be strictly followed so that theoretically, a Git hook script can be used to automatically build and roll-out the software to production servers every time there is a commit on main.

Supporting branches

Used to aid parallel development between team members, ease tracking of features, prepare for production releases and to assist in quickly fixing live production problems. They will be removed eventually.

• Feature branches
• Release branches
• Hotfix branches

Feature branches

Used to develop new features for the upcoming or a distant future release. It exists as long as the feature is in development, but will eventually be merged back into develop or discarded.

Feature branches typically exist in developer repositories only, not in origin.

• May branch off from: develop
• Must merge back into: develop

Naming convention

• Anything except main, master, develop, release-*, or hotfix-*
• Use - as separators
• Include issue number (e.g., feature-1532-add-backend)
• Use issue name if possible

Incorporating a finished feature on develop

Finished features may be merged into the develop branch to definitely add them to the upcoming release:

The --no-ff flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups together all commits that together added the feature.

Release branches

Used to support preparation of a new production release. They allow for minor bug fixes and preparing meta-data for a release (version number, build dates, etc.) to clear the develop branch to receive features for the next release. The upcoming release gets assigned a version number exactly at the start of a release branch

The key moment to branch off a new release branch from develop is when develop (almost) reflects the desired state of the new release. At least all features that are targeted for the release-to-be-built must be merged in to develop at this point in time. All features targeted at future releases must wait until after the release branch is branched off until they can be merged.

• May branch off from: develop
• Must merge back into: develop and main
• Branch naming convention: release-*

Conditions for creating a release branch

• The current production release and the state of develop is ready for the “next release”
• The release version is decided (e.g., 1.2 rather than 1.1.6 or 2.0)

Creating a release branch

1. Create a new branch from develop with its name reflecting the new version number (e.g., release-1.2)
2. After switching to the new release branch, bump the version number to reflect the new version.
   • Can be done manually or with a shell script that changes some files in the working copy
3. Commit the bumped version number

Before the release

• A release branch may exist for a while until the release can be rolled out definitely
• Bug fixes may be applied in the branch during this period
• Adding large new features is strictly prohibited (they must be merged into develop and wait for the next release)

Finishing a release branch

1. Merge the release branch into main with git merge --no-ff (every commit on main is a new release by definition)
2. Tag the commit on main for easy future reference to this historical version with git tag -a <version-number>
3. Changes made on the release branch must be merged back into develop with git merge --no-ff(for future releases to also contain the bug fixes)
4. Delete the merged release branch

Hotfix branches

Used to prepare for a new production release for unplanned scenarios must be resolved immediately, such as an undesired state of a live production version caused by a critical bug. A hotfix branch may be branched off from the corresponding tag on the main branch that marks the production version. The hotfix branch allows team members to be able to continue work (on the develop branch), while another person is preparing a quick production fix.

• May branch off from: main
• Must merge back into: develop and main
• Branch naming convention: hotfix-*

Conditions for creating a hotfix branch

• The current production release running live but causing problems due to a severe bug
• Changes on develop are yet unstable

Using the hotfix branch

1. Create a new branch from main with its name reflecting the hotfix version number (e.g., hotfix-1.2.1 for a bug from version number 1.2)
2. After switching to the new hotfix branch, bump the version number to reflect the hotfix version.
   • Can be done manually or with a shell script that changes some files in the working copy
3. Commit the bumped version number
4. Fix the bug and commit the fix in one or more commits

Finishing a hotfix branch

Similar to fishing a release branch:

1. Merge the hotfix branch into main with git merge --no-ff
2. Tag the commit on main for easy future reference to this historical version with git tag -a <version-number>
3. If a release branch exists during the hotfix, changes made on the hotfix branch must be merged into the release branch with git merge --no-ff
4. Otherwise, changes made on the hotfix branch must be merged back into develop with git merge --no-ff
5. Delete the merged hotfix branch