Skip to main content

Commit messages

This specification uses the Conventional Commits format. Commit types are partly inspired by the Angular commit message format.

Format of the commit message:

<type>(<optional scope>): <description>

<optional body>

<optional footer(s)>

Example commit:

refactor(dist-pack): use tag notation for header format

Co-authored-by: Sebastian Iffland <sebastian.iffland@fullhaus.de>

You might have a look at the examples from Conventional Commit or any of the most recent FULLHAUS projects.

Types​

  • feat Changes which introduce a new feature
  • refactor Changes which neither fix a bug nor add a feature
  • fix Changes which patch a bug
  • build Changes which affect the build system or external dependencies (e.g. webpack, composer)
  • chore Changes which are not user-facing
  • style Changes which do not affect code logic, such as white-spaces, formatting
  • ci Changes which affect CI configuration files and scripts
  • docs Changes which affect documentation
  • perf Changes which improve performance
  • revert Changes which revert a previous commit (see Revert commits)
  • security Changes which improve security
  • test Changes which add missing tests or correct existing tests

Breaking changes can be part of any commit type. To indicate that use an appended ! after the type/scope. Furthermore, mentioned it as a breaking change block in the footer, which should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then the description of the change, justification and migration notes.

Scope​

Scope can be anything that specifies the place of the commit change. Usually this describes the affected part of a build system or extension/plugin. For example dist-pack, npm, composer, ...

  • scope names must not contain whitespaces nor underscores
  • scope names must be lower-kebab-case

Subject​

Should provide a short and concise description of the change.

  • use the imperative, present tense: “change” not “changed” nor “changes”
  • don’t capitalize the first letter
  • don’t use a dot (.) at the end

Body​

  • Just as in the description, use the imperative, present tense.
  • Should explain the motivation for the change and/or provide additional information.

The footer should contain information about breaking changes as well as reference e.g. PRs that this commit closes or is related to.

Referencing issues​

Closed issues should be listed on a separate line in the footer prefixed with a keyword like Closes or Resolves, e.g.:

Closes #234

or in case of multiple issues:

Closes #123, #245, #992

Revert Commits​

In addition to the revert type, include the following commit message footer:

Refs: <8-character hash of the commit being reverted>

Plugin​

To make life easier you should use the Conventional Commit Plugin for JetBrains IDEs.

Using custom tokens​

Custom tokens allow you to override the default list of commit types and scopes.

Project specific configuration​

Each project should come with its own custom conventionalcommit.json file inside the project root. Under Conventional Commit > Default tokens check the Custom file checkbox and set its path correspondingly.

General configuration (not specific to any project)​

In case the above-mentioned file is not included in the project root, I would recommend placing a general configuration file inside your user's home directory, preferably a subfolder named .conventionalcommit.