Why

Adopting best practices for Git Branching, Versioning, Commit message formats, and Release process simplify developer workflow and provide a great Developer Experience (DX)

Here, we’ve standardised on:

• GitFlow as git branching model

• Semantic-Release for release process

• Semantic Versioning 2.0.0 for versioning

• Conventional Commits for commit messages

This gitBook explains how we’ve adapted GitFlow and the GitFlow's git extension tools for working with Git Repository. This is how we work internally, and we’re sharing this in the hope that others find it useful too.

Semantic Release

Semantic-Release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.

Highlights

• Fully automated release

• Enforce Semantic Versioning specification

• Use formalized commit message convention to document changes in the codebase

• Publish on different distribution channels i.e, SNAPSHOT on develop, hotfix branches and Stable in master branch

• Avoid potential errors associated with manual releases

Semantic Versioning

Source of truth for version come from Latest/Highest git tag on Master branch

Semantic Versioning 2.0.0 given a version numbering convention MAJOR.MINOR.PATCH, increment the: i.e., 1.9.0 -> 1.9.1 -> 1.10.0 -> 2.0.0

• MAJOR version when you make incompatible API/Breaking changes,

• MINOR version when you add functionality in a backwards compatible manner, and

• PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Note: goLang projects need `v` version prefix. So you have to use `v<SemVer>`

Tools

• For Angular projects use ngx-semantic-version
• For Java projects use axion-release-plugin Gradle plugin
• For GoLang projects use git-chglog

Conventional Commits

Conventional Commits is a specification for adding human and machine readable meaning to commit messages

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject.

<type>(<optional scope>): <subject>
<BLANK LINE>
<optional body>
<BLANK LINE>
<optional footer(s)>

The header is mandatory and the scope of the header is optional.

Common types according to commitlint-config-conventional (based on the the Angular convention) can be:

• build

• ci

• chore

• docs

• feat

• fix

• perf

• refactor

• revert

• style

• test

• BEAKING CHANGE:

Real world examples can look like this:

chore: run tests on travis ci
fix(server): send cors headers
feat(blog): add comment section

Tools

• Commitizen
• Commitlint

Changelog

On release branch, generate CHANGELOG.md and commit it, before merging back to develop & master.

Generate changelog using git-chglog.

The format is based on Keep a Changelog, and adheres to Semantic Versioning.

# first time
git-chglog --init
# on release
git-chglog -o CHANGELOG.md
git-chglog -o CHANGELOG.md -next-tag 2.0.0

Tools

• git-chglog

GitFlow

Gitflow is a branching model for Git, created by Vincent Driessen. It has attracted a lot of attention because it is very well suited to collaboration and scaling the development team.

TL;DR Checkout How It Works and Gitflow Usage

Key Benefits

1. Parallel Development

   One of the great things about GitFlow is that it makes parallel development very easy, by isolating new development from finished work. New development (such as features and non-emergency bug fixes) is done in feature branches, and is only merged back into main branch of code when the developer(s) is happy that the code is ready for release.

2. Collaboration

   Feature branches also make it easier for two or more developers to collaborate on the same feature, because each feature branch is a sandbox where the only changes are the changes necessary to get the new feature working. That makes it very easy to see and follow what each collaborator is doing.

3. Release Staging Area

   As new development is completed, it gets merged back into the develop branch, which is a staging area for all completed features that haven't yet been released. So when the next release is branched off of develop, it will automatically contain all of the new stuff that has been finished.

4. Support For Emergency Fixes

   GitFlow supports hotfix branches - branches made from a tagged release. You can use these to make an emergency change, safe in the knowledge that the hotfix will only contain your emergency fix. There's no risk that you'll accidentally merge in new development at the same time.