1 Introduction

Introduction

Did you ever found yourself in a situation where needed to collect all notable changes while you've changed a lot of code, scattered over a dozen commits? All this for updating your changelog manually? We did. And we got tired of it.

That's why we decided to improve our commits by being more strict when it comes to tagging, commit-titles and body. With those being standardized, they can be used to generate a changelog automatically. All we have to do now, is to execute the generator manually, or invoke the generator in automation scripts like CI or git-hooks.

Commit guidelines

As part of standardization, you could follow the guidelines below. Adapt them to fit you own needs.

• Commit messages must have a title line and may have body copy.
  These must be separated by a blank line.

• The title line must not exceed 50 characters.

• The title line should be capitalized and must not end in a period.

• The title line must be written in an imperative mood.
  (Fix, not Fixed / Fixes, etc.)

• The body copy must be wrapped at 72 columns.

• The body copy must only contain explanations as to what and why, never how.
  The latter belongs in documentation and implementation.

Title Line Standard Terminology

First Word	Meaning
Add	Create a capability e.g. feature, test, dependency.
Cut	Remove a capability e.g. feature, test, dependency.
Fix	Fix an issue e.g. bug, typo, accident, misstatement.
Bump	Increase the version of something e.g. dependency.
Make	Change the build process, or tooling, or infra.
Start	Begin doing something; e.g. create a feature flag.
Stop	End doing something; e.g. remove a feature flag.
Refactor	A code change that MUST be just a refactoring.
Reformat	Refactor of formatting, e.g. omit whitespace.
Optimize	Refactor of performance, e.g. speed up code.
Document	Refactor of documentation, e.g. help files.

Title lines must never contain (and / or start with) anything else.

Using these guidelines, our changelog becomes like the one in our repository. Click here to view it.