Commit Messages

The team at d-centralize established some very precise rules about how Git commit messages should be formatted. This leads to more readable messages that are easy to follow when looking through the project history. Also, the Git commit messages may be used to generate Git changelogs.

The commit messages are a form of communication between developers. Especially when code review is involved, the commit messages aid the reviewer to understand what the commit is about.

A clear commit message also helps to create clean commits. When a commit message contains several subjects the commit can probably be split into multiple commits.

More details on which the structure is based can be read in this note about Git commit messages.

Structure

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}({scope}): {subject}
<BLANK LINE>
{body}
<BLANK LINE>
{footer}

The first line of a commit message is its header. It consists of a commit type, a scope and a brief description of the change, preferably no longer than 50 characters.

Type

The type defines what sort of change is made.

The following are allowed:

chore: Changes to the build process or auxiliary tools
docs: The definition of the second term.
feat: The definition of the second term.
fix: Bug fix
perf: Performance improvement
refactor: A code change that neither fixes a bug, nor adds a feature
style: Fix a code style issue
test: Adding missing tests

chore

Changes to the build process, auxiliary tools or configuration files; e.g. updates to a .gitignore, package.json or setup.py.

chore(gitignore): ignore node_modules
chore(setup): bump version
chore(eslint): implement ESLint
chore(karma): fix coverage by locking karma-coverage

docs

Updates to documentation. This may be any sort of changes to either rendered documentation or inline comments.

docs(builder): fix typo in comment
docs(startup): add missing documentation for startup view
docs(render): clarify ambiguous description

feat

Add a new feature. A new feature is always accompanied by a test.

For an end user project, a feature is something new that the user can experience, such as a new view.

For a library, a feature is a new functionality that is added and can be used by those using the library.

feat(app): allow user to select dark themes
feat(format): implement XML HTTP responses

fix

Fix a bug. A fix consists of modified code, along with a new test that would fail in the old situation, but works in the new situation.

fix(api): prevent duplicate logging
fix(http): don't fail for incorrect content types

perf

Any sort of performance improvements.

perf(analyser): make analyses 50% faster
perf(fibo): rewrite using a less CPU intensive formula

refactor:

A code change that neither fixes a bug, nor adds a feature.

refactor(foo): rename foo module to bar
refactor(names): organize name list alphabetically

style

Fix a code style issue. Such a change may be accompanied by the integration of a new plugin for a tool to enforce the new style.

style: change double quotes to single quotes
style: apply eslint-plugin-promise

test

Add missing tests

test(e2e): add missing e2e test for adding parts
test(login): add missing test for logging in

Scope

The scope specifies the location of the change, such as Dockerfile or .gitignore.

The scope for changes to a Python class or function is always the name of that class or function. Note that a change to a method of a class is considered a change to a class. Changes to setup.py{.interpreted-text role=“file”}, dev-dependencies.txt or similar files should have the scope setup.

In case the change is not limited to one location, just leave it out.

Subject

The subject should use a present-tense imperative: change, not changes or changed.

Don’t capitalize the first word or add a period (.) at the end of the subject.

If a commit message contains the word “and”, it could probably be split into multiple smaller commits.

Message Body

Separate the message body from the subject with a blank line. The body may have lines up to 72 characters long.

It includes the motivation for the change and points out differences from previous behavior. The body should be written using correct English sentences.

Message footer

A commit message may refer to a GitLab issue number. Each time a new patch set is pushed to code review, a link to the change request will be added to the issue.

Refs: #<number>

If the keyword Fixes or Closes is used instead of Refs, the issue will be closed automatically when the change is merged.