Conventional Commits

Conventional Commits is a way of standardizing commits within a software development project, using simple and clear rules to make commits more descriptive and consistent. This helps reduce the time spent understanding how and why something was done when making a later change or fix.

Commit format

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Type

The type determines the nature of the commit, which can vary according to the changes made to the code and can be one of the options below:

TYPE	DESCRIPTION
feat	Adds a new feature
fix	Fixes a bug or unexpected behavior
style	Changes code formatting without changing behavior, such as whitespace or indentation
refactor	Restructures code without changing behavior to improve its quality and organization
perf	Changes code to improve performance
test	Adds or updates automated tests
docs	Adds or updates documentation, such as API docs or READMEs
build	Changes the software build process, such as compiler or Docker settings
ci	Changes continuous integration settings, such as code analysis tools
chore	Maintenance that does not affect visible software behavior and does not fit another type
revert	Reverts an earlier commit

Note: The type is required.

Scope (optional)

The scope provides contextual information about the commit. It can be a one- or two-word summary of the changes made or, for example, the name of the system module in which the changes were made.

Description

The description briefly states what the commit changes.

Note: The description is required.

Body (optional)

The body gives a detailed description of the changes and may include, for example, the motivation for the changes or a brief explanation of how behavior differs from before.

Footer (optional)

The footer provides additional information, such as a task number or related libraries.

Commit examples

Here are several examples of commits for each type.

feat

feat(language): add Brazilian Portuguese translation

feat(inventory): add option to filter records by description

feat(paypal,payment)!: add PayPal payment option

Add a "Pay with PayPal" button to checkout and integrate the backend with the PayPal API

BREAKING CHANGE: The payment API now supports PayPal. Clients using the previous API version must update their integrations

What is a BREAKING CHANGE?

The BREAKING CHANGE keyword is used to indicate a significant change in the software that may affect compatibility with previous versions and break other parts of the system. This information is useful to other developers who may need to update their own systems to accommodate the changes made.

A BREAKING CHANGE can be indicated in the footer with the keyword or with a ! after the type or scope.

fix

fix: correct typo in billing error message

fix: resolve compilation error on older operating systems

Refs: CS-112

fix(auth): fix authentication error when using biometric authentication

The error was fixed by updating the biometric authentication library to a newer version

Refs: CS-113

style

style: update indentation in replication routine

style(order,billing): remove blank line

style(layout): standardize indentation of the homepage component

Adjust the component's whitespace without changing the page's appearance

refactor

refactor: update method after code review

refactor: simplify if-else logic

refactor(layout): restructure layout components

The code was split into smaller, more specific components to make problems easier to identify and fix

perf

perf: optimize search algorithm to improve response time

perf: improve login page response time

perf(component): update chart rendering logic

Use a more efficient approach to calculate and render data, reducing loading time and improving user interactivity

test

test: add unit tests for billing routine

test(service): add unit test for password validation

Test validatePassword() with passwords of different levels of complexity to check whether the function returns true or false for each one

test(service): add tests for notification service

Ensure notifications are sent correctly to users and displayed correctly in the user interface

docs

docs: update logging API documentation

docs: fix spelling in changelog

docs(installation): update installation documentation

Update the installation documentation with information about the latest software versions and system requirements

build

build: update compiler version

build(docker): update Dockerfile settings

Add steps to ensure project dependencies are installed correctly

build(dev): fix development environment configuration

Adjust environment variables so scripts run correctly in development

ci

ci: add security check to CI pipeline

ci: integrate vulnerability analysis tool

ci(github-actions): update GitHub Actions workflow

Update the workflow to ensure tests run correctly across different operating system and browser versions

chore

chore: update project dependencies

chore!: drop support for Node 6

BREAKING CHANGE: Refactor to use JavaScript features unavailable in Node 6

chore: resolve merge conflict

Resolve a merge conflict caused by an unrelated change made by another developer

revert

revert: revert commit made on the wrong branch

Notes and suggestions

• One very important detail when using this commit convention is to write in the imperative mood.

Correct:

feat(mvcp): add mvcp contracts

Incorrect:

feat(mvcp): added mvcp contracts

You should always describe what the commit will do, not what you did in the commit!

• Do not capitalize the first letter of the description in the commit message.

This is not mandatory, but it is an important detail to agree on if you work in a team. It is also worth defining a convention for whether the commit message will be written entirely in lowercase or not.

• Do not use a period (.) at the end of the commit message.

• Separate multiple scopes with a comma (,) or a slash (/).

One suggestion is to always choose one of the two conventions, especially when working in a team.

• Define a character limit for the commit description.

The purpose of the description is to explain the commit briefly, so the description can have a character limit (for example, a maximum of 80 characters).

If the changes need to be described in more detail, that should be done in the commit body!

Still not sure whether Conventional Commits is a good idea?

Commit messages written according to Conventional Commits can be processed automatically by tools such as semantic-release, which uses the information in the commits to determine the next software version and automatically generate a changelog.

More information can be found on the official Conventional Commits website.