5. Git Workflow

Quick Access

• Introduction
• Branching
  • Main branch
  • Development branch
  • Feature branches
  • Bugfix branches
  • Hotfix branches
  • Release branches
  • Overview
• Commits
  • Commit message
  • Commit changes
• Tags
  • General
  • Recommendation
• Git usage policies
  • Squash
  • Rebase

Introduction

This document describes the Git-Workflow which is used by the KatApp development team. The Git-Workflow described in this document mainly follows the workflow originally published and popularized by Vincent Driessen.

Branching

The workflow describes several different branch types. Each of these branch types has a specific role associated with it.

Main branch

The main branch represents, as the name suggests, the branch where all changes sooner or later end up in. In this workflow, the main branch always reflects a production-ready state. When deployments of the project are created, they are always built from the main branch.

As this branch is usually critically tested, it is not allowed to directly commit to this branch.

The only branches which are accepted to be merged into the main branch are:

• develop
• release
• hotfix

Accepted naming conventions for this branch are:

• main

Development branch

The development branch, usually called develop, is a branch which runs parallel to the main branch. The development branch reflects the state with the latest development changes, which are about to be included in the next upcoming release.

This workflow also suggests to block direct commits to the develop branch, as it may cause conflicts with the rest of the workflow.

Accepted naming conventions for this branch are:

• develop

Feature branches

Feature branches are used to, guess what, implement new features. A feature can include a wide variety of tasks. Feature branches usually directly correspond to either user stories or subtasks, hence it is allowed to directly push commits to them.

Feature branches use a very specific naming scheme, which is directly correlated to issue ID’s. Issues, typically maintained in an integrated or external project management tool, usually have incremental ID’s prefixed with some project key, e.g.:

• katapp-3128
• katapp-732

Those ID’s need to be referenced in any feature branch. Moreover, feature branches use the prefix feature/.

Not mandatory, but typically appreciated, are some short descriptions added to branch name. Most of the time, those are some buzz words used by the task to describe what needs to be implemented. However, take care that branch names aren’t getting too long, nobody wants to read this:

• feature/katapp-2256-update-global-user-architecture-documentation-with-markdown

Accepted names for feature branches would be:

• feature/katapp-732-update-docs
• feature/katapp-3128-backend-endpoint-get

Bugfix branches

In their core, bugfix branches work exactly the same way as feature branches, except for the fact that they are exclusively used for bugs. Bugfix branches follow the same naming convention as the feature branches, except that they use the prefix bugfix/ instead of feature/.

Accepted names for bugfix branches would be:

• bugfix/katapp-452-user-exception
• bugfix/katapp-3746-backend-initialization

Hotfix branches

Hotfix branches are the only branches created directly from the main or a release branch and directly merged into the main and/or corresponding release branch. Those branches are used when you quickly have to patch a production issue. An advantage of this branch type is, that it allows you to quickly deploy a fix for a production issue without disrupting the workflow of other developers and without waiting for the next release.

Once the fix is merged into the main branch, the branch must also be merged into both the development branch and the current release branch, if there is one. This process ensures that everyone who starts implementing a new feature has the latest code.

Hotfix branches use the prefix hotfix/ to distinguish them from feature, bugfix and release branches.

Accepted names for hotfix branches are:

• hotfix/katapp-5175-app-start-failure

Release branches

Release branches mark, as the name suggests, releases. Release branches are branched of the development branch, after all features planned for the release have been merged into it.

No code related to new features should be added to release branches. Only content which corresponds to this release is added to the release branch. Such content can include documentation, bug fixes and other, similar tasks related to a release.

Similar to hotfix branches, release branches are merged into the development branch as well, after they have been merged into the main branch. This process ensures, that the development branch also uses the latest code.

As far as naming conventions go, release branches use the prefix release, followed by the currently released version.

Accepted names for release branches are:

• release/4.2
• release/5.0.1

Also accepted are releases marked as alpha or beta releases, or preview releases:

• release/0.0.1-alpha
• release/0.2-beta
• release/0.9-preview

Important: release branches are not deleted after they have been merged. They remain as stale branches, to provide the possibility to redeploy older versions or even cherry pick certain fixes into older releases.

Overview

The illustration below provides an overview over the different branch types and how they interact with each other.

Commits

Commits are the core building block of any Git project. This sections describes all rules and recommendations when working with commits.

Commit message

Entering the commit message is one of the most central stages of any commit. This is the short description of what has been done inside the commit. Moreover, the commit message is the first thing any developer sees, when looking at the Git history. As a consequence, a commit message should be short, clear and precise.

Examples for good commit messages are:

• Added feature to switch between light and dark mode
• Fixed a bug where the user cannot navigate to the previous view
• Added unit tests for <module, type, ...>

Commit messages should relate to a feature, bugfix, hotfix, release and similar tasks, therefore, although issue ID’s are already used in the name of the branch, commits should be prefixed with the same issue ID as the branch it is committed on. This process is implemented, because after a branch has been merged, there is no correlation between commit and issue anymore.

As a consequence, commit messages always start with the issue ID they relate to. Examples for valid commit messages are:

• katapp-483: Added feature to switch between light and dark mode
• katapp-1932: Fixed a bug where the user cannot navigate to the previous view
• katapp-3291: Added unit tests for <module, type, ...>

Commit changes

Generally, it is recommended to keep commits relatively small. Changes within one commit ideally should be related to each other. Also, it is preferred that the project can be built successfully after each commit, so prevent to commit broken code.

Tags

General

Tagging in Git is generally used to capture a point in history that is used for a marked version release (i.e. v1.0). A tag is like a branch that doesn’t change. Unlike branches, tags, after being created, have no further history of commits.

Recommendation

As releases are already marked with release branches, which remain in the repository anyway, it is recommended to not use tags at all.

Usage

If tags are used nontheless, use them to mark releases. If you do, use a naming convention which is analogous to the one of release branches.

Accepted tag names would be:

• 1.0
• 4.2.1
• 5.0-alpha
• 5.2-beta
• 6.9-preview

Note: If you use version tags, make sure the tags are in sync with the release branches.

Git usage policies

Squash

Git merges offer the possibility to squash commits. This workflow recommends squashing the commits of branches, which are merged back into the development branch, i.e. feature and bugfix branches. Also, merges back into master should never be squashed.

Why is this workflow recommending git squashing? The implementation of new features can be, and is more often not, very messy in terms of commit history. To make sure the Git history is as clean and as readable as possible, squashing is recommended according to the ruleset defined above.

Rebase

Generelly it is recommended to avoid all Git operations which potentially alter the Git history. These operations should only be used in exceptional cases.

Force

May the force never be with you, remember that. In other words, do not you any git force ever.