Conventional Commits

Translated from German using DeepL.

Date: January 2021
Reading time: 3 minutes

add new modifier
improve hbs file
work on heading
improve code

I found these commits in my repository. It is clear that these messages have not been chosen optimally.
But how should they be written? Is this message even important?

Advantages

There are rules regarding these messages. You can read more about this standardization here (opens in a new tab).

The following advantages arise if you adhere to these rules:

The messages are standardized (this is especially helpful in a team)
Commits can be sorted more easily
You can always see exactly what a commit was made for
If you are looking for a commit, the categories help you

Structure

A commit message should be structured like this:

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

Type

The type is used to define what kind of change is involved. The following options are available for this.

Type	Description	Example
build	extern dependencies	install npm
ci	CI changes	build the site
docs	documentations	add setup information to the readme
feat	new feature	button can now open a new page
fix	fixed bug	accordion can be folded up again
perf	change in code which impacts the performance	swap part of a code into function
refactor	change in code which neither fixes a bug nor is a feature	rename variable
style	changes that do not change functionality from code	format JS file, remove spacing and add semicolons
test	add or improve tests	write a cypress test

If the commits are clearly categorized, this makes it easier to sort them later.

Revert

If the commit reverts another commit, this should also be marked in the type. It also makes sense to include the SHA from the old commit in the message. A revert commit could therefore look like this:

revert: this reverts commit cba73d9466f2081c450397e45529903126de25c8

Scope

In the scope, you write which branch it is. Examples could be:

(homepage)
(image)
(stage)

In GitLab you can already sort the tickets by branch. After a merge request, however, the origin of a commit is not directly visible. It is therefore advisable to specify this optional scope.

Description

Here you can describe what you have done. Important:

Always write in the present tense
Letters are written in lower case
Even if it is a sentence, do not use a period at the end

Tip: Such a message should be approx. 50 characters long.

Body

The reason for the change is explained in the body. You can also describe in more detail what has changed. Otherwise, the same rules apply as in the description.

Footer

In the case of serious changes, the issue that is closed with the commit can be referenced here. Such changes are marked with BREAKING CHANGE or a !.

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

You can also mark a breaking change with a !.

refactor!: drop support for Node 6

Example

This is what your future commits could look like.

docs(image): write a new readme for the img pattern

this pattern without a readme would not be useful

feat(button): add new functionality to open the overlay

BREAKING CHANGE: change the script language form js to ts

Commit Linting

How can I make sure that I follow the rules?
There are countless npm packages to help you with this. Examples:

commitizien: https://github.com/commitizen/cz-cli (opens in a new tab)
commitlint: https://github.com/conventional-changelog/commitlint (opens in a new tab)

Opinion

The aim should always be that a commit is something independent. In addition, it must not be too large. This is guaranteed with these rules, as a commit must be of a certain type.
It takes a little more time to create these commits. In return, they are easier to understand later and you have a better overview. Searching for older commits in particular is easier as you can filter by type.
If you work in a team, it makes sense to stick to such agreements. This way you can also manage the commits of others.

So I see more advantages than disadvantages if you stick to the rules.