Conventional Commits¶

What?¶

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

The full spec can be found here

Why?¶

• As we use linters to make our code uniform and polished, we need to have a unified and detailed way to describe our commit history.
• It will be extremely easy to integrate tools that use this convention, for example, an automatic CHANGELOG.md generator.
• Automatically determining a semantic version bump (based on the types of commits landed).
• Communicating the nature of changes to teammates, the public, and other stakeholders.
• Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.

How?¶

• First of all, this can be implemented without any new (or fancy) tool. It's just about the way we compose the commit messages. They should comply to the following template:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit contains the following structural elements, to communicate intent to the consumers of your library:

• fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning).
• feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
• BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.
• types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.
• footers other than BREAKING CHANGE: may be provided and follow a convention similar to git trailer format.

A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays.

Examples can be found here

Can I see an example project?¶

Yeah! Take a look at this one

• CHANGELOG.md
• Commit History

Tools¶

In order to make our life easier, there are several tools we can use:

Commitizen¶

• It's a NodeJs based tool that can be used to present a user friendly wizard that will help you writing the commits following the standard.
• It can be used on any project type by doing git cz. Note: you don't need to configure anything special on the project to start using it. https://github.com/commitizen/cz-cli#if-your-repo-is-not-commitizen-friendly.
• Website https://commitizen.github.io/cz-cli/,

Standard Version¶

• A tool that will generate a CHANGELOG.md, the corresponding tags and even bump the package.json version (only NodeJs),
• Before a release, you can just call standard-version and the tool will do the magic for you.
• It works really good with NodeJs based projects.
• Website: https://github.com/conventional-changelog/standard-version.

Conventional Commits for Java¶

• A mvn (and Gradle) plugin to generate the CHANGELOG.
• note: We haven't tried this tool yet.
• Website: https://github.com/foo4u/conventional-commits-for-java