1 Introduction

Introduction

Did you ever find yourself in a situation where you 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!

So, we decided to improve our commits by being stricter 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.

Making changes

Create a separate branch for each set of unrelated changes.
This makes it easier for reviewers to give feedback and for you and future collaborators to understand the changes and to revert or build on them.
Additionally, if there is a delay in one set of changes, your other changes aren't also delayed.

Ideally, each commit contains an isolated, complete change.
Again, it makes it easier for you and future collaborators to understand the changes and to revert or build on them.

Commit guidelines

As part of standardization, you could follow the guidelines below. Adapt them to fit your 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 (first character) 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 the 72nd column.

• The body copy must only contain a summary of the changes with an explanation 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.