Semantic Git

May 27, 2016

frontpage git tutorial

Ever looked at a git branch name and had no idea what version of the product it belonged to? Or tagged a release and wondered if it should be a minor bump or a patch? This post is about eliminating that ambiguity by combining two things that already work well on their own – git-flow and semantic versioning – into a single workflow where each reinforces the other.

Semantic git-flow

Background

skip TLDR;

Semantic Versioning

At a high-level Semantic Versioning aims to solve dependency issues by creating a standard versioning system that allows anyone to understand what has changed in a new version.

Example

1.2.3

Major.Minor.Patch

Major: Changing this is mandatory in the case of a backwards incompatible api change.
Minor: Changing this is mandatory in the case of a backwards compatible api change or addition of new features.
Patch: Changing this is mandatory in the case of any other change, that is not adding functionality or breaking backwards compatibility.

Git Flow

A git workflow that dictates what branches to make and why. A typical git-flow workflow will include 3+ branches:

stable: the current stable branch
master: the current development or HEAD
master-feature: where the work is actually accomplished

The git flow workflow is designed so that:

hot-fixing the stable product is always possible
new features can be added to the stable product by merging in the feature branch
git history remains linear to that it doesn’t become git branch spaghetti

Semantic git

By merging these two ideas we can make it clear what is in development on any branch at any time and what that means to the product.

Stable

1.2.3: By utilizing semantic versioning we can always keep it clear what our stable code is by using tags to snapshot stable code. In this way stable wouldn’t be a branch but rather a tag. Since the patch number should increment any time there is a new stable release this should be a sane mechanism for it.

master

1.2.x: There could me multiple master branches, one of any supported major.minor version combination. No work should be done directly on the master branches.

master-feature

1.2.x-feature: It is obvious what is being worked on in the branch and what master version it is based on.

Workflow

Initialize git and create master branch
git init
git checkout -b 1.0.x
git push -u origin 1.0.x
Create new branch for “Checkout Widget” feature development
git checkout -b 1.2.x-checkout-widget
Work on project
git fetch
git pull --rebase origin 1.2.x
git push origin 1.2.x-checkout-widget
Create merge request in Gitlab or a pull request in github (shown here is what happens on the command line)
git checkout 1.2.x-checkout-widget
git pull --rebase 1.2.x
test and peer review
git checkout 1.2.x
git merge 1.2.x-checkout-widget

> This is also handy if you are working on your own sub-feature branches that do not require further peer review.

Create release tag and publish new release
- Patch release
  1. git tag 1.2.4 Assumes the current release is 1.2.3
  2. git push origin 1.2.4
- Minor release
  1. git tag 1.2.0 Assumes the current release is 1.1.<any-number>
  2. git push origin 1.2.0
  3. git checkout -b 1.3.x
  4. git push -u origin 1.3.x

Notice the new Minor Release comes from the branch of the same name. Same is true of Major Releases. As soon as it is known that backwards compatibility will be broken, then new Major Release branch should be made. Before work is started on a new feature, a new Minor Release branch should be made.

Why this works

The naming convention does the heavy lifting. Anyone on the team can look at a branch name like 1.2.x-checkout-widget and immediately know what version it targets and what feature is being built. Tags become the single source of truth for what is stable. There is no guessing, no spreadsheet of version numbers, and no ambiguity about what is in production. The workflow enforces the versioning and the versioning gives the workflow meaning.