Git Conventional Commits

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.

• Automatically generating CHANGELOGs.
• 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.
• Triggering build and publish processes.
• Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.

Specification

Conventional Commits^[1] specifies the structure of the commit message:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type

The type must use lowercase, cannot empty, followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.

There are all available commit types:

• build
• chore
• ci
• docs
• feat
• fix
• perf
• refactor
• revert
• style
• test

Scope

A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis.

Description

The description is a short summary of the code changes, cannot be empty, and does not end with a period.

Body

A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.

A commit body is free-form and MAY consist of any number of newline separated paragraphs.

Footer

One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a :<space> or <space># separator, followed by a string value.

A footer’s token MUST use - in place of whitespace characters, a only exception is made for BREAKING CHANGE.

A footer’s value MAY contain spaces and newlines.

Correlate with SemVer

Some commit types may affect SemVer changes:

1. fix means patches a bug, this correlates with PATCH in Semantic Versioning.
2. feat means introduces a new feature, this correlates with MINOR in Semantic Versioning.
3. BREAKING CHANGE is in the footer, or appends a ! after the type/scope, this correlates with MAJOR in Semantic Versioning.

Tools

Gitmoji

Gitmoji^[2] is an initiative to standardize and explain the use of emojis on GitHub commit messages.

VS Code Extension

When committing in the VS Code, Conventional Commits^[3] extension can help to generate a commit message.

GitHub Action

Release Please Action^[4] is a GitHub Action, which can auto-generate and create releases based on commit messages.

Release Please Action will automatically create release pr includes generated CHANGELOG. When PR is merged, it will create a release, and you can run CI/CD and upload files to the release.

References

1. "Conventional Commits". Retrieved June 28, 2022. ↩
2. "gitmoji". Archived from the original on June 28, 2022. Retrieved June 28, 2022. ↩
3. "Semantic Versioning". Archived from the original on June 28, 2022. Retrieved June 28, 2022. ↩
4. "Release Please Action". Archived from the original on June 28, 2022. Retrieved June 28, 2022. ↩