One of the advantages of using version control is to be able to have at hand all the history of our project, compare changes, know when they were introduced, by whom and in the case of having to revert to be able to do it in a fast and reliable way.

At the same time that we want to leave a thorough record of how the development has gone, we have to make sure that the record is understandable to someone new to the team.

What is conventional commits

It is a convention when formatting the commit messages of our project. It defines a set of rules that the whole team will respect and speeds up the reading of commits from the repository and allows us to automate certain actions such as the versioning of the application.

Conventional commits are closely linked to Semantic Versioning. Semantic Versioning a specification that is followed for versioning applications in software development.

Version 3.2.1

MAJOR = 3
MINOR = 2
PATCH = 1

Increments of major, minor or patch indicate:

• Major: an increment that makes the API incompatible with the new changes.
• Minor: an increment indicates that functionality has been added but without breaking compatibility.
• Patch: an increment indicating that a bug has been fixed but without breaking compatibility.

How to use Conventional Commits

The way Conventional Commits defines how our commit messages should look like can be summarized as follows:

{type}(scope): {description}

{body}

{foot from commit}

Type

The type describes the character of the commit. So, anyone who reads it will quickly understand what type of change we have introduced, there are some proposed:

• featwhen our change adds a new functionality.
• fixin case the commit fixes a bug in our project.
• testis used to introduce new tests.
• docs: to add or correct project documentation.
• refactorThe refactoring tool: as its name suggests, it is used to introduce refactoring changes.
• revertwhen we need to revert a change already introduced in the branch.

In addition, there are complementary ones that are somewhat more specific:

• chore: maintenance or environment configuration changes, such as putting new libraries into package.json or changes in the .gitignore.
• build: changes in the project compilation process.
• ci: changes affecting our continuous integration environment.

Scope

The scope serves to give context about the change we are introducing. We can use it to communicate that we are touching the part of the core of the project, or perhaps a specific module of the project such as translations or the database.

Description

According to the Conventional Commits specification, the description should be:

• Concise, following the colon after the type.
• It must include a brief summary of the changes applied.
• Use of present tense verbs such as includingof, add o allow.

Body

The body of the commit is optional. It is usually included when the description is very short to give more context about the change introduced. There is no specific rule on how it should be written, it has a free format.

Caption

Just as the body is optional. It is usually used to indicate that the change introduces changes that break backward compatibility, as do the major changes in Semantinc Versioning. The footer must include BREAKING CHANGES in that case, or we can put a ! after type/scope

BREAKING CHANGES: {description}

feat!: add new service to the user controller

Examples

Commit with description and breaking changes

feat: add new message suscriber

BREAKING CHANGE: this changes involve to change the messages sent to this app

Commit with ! instead of using BREAKING CHANGE

feat!: new user email template added to the finished book service

In conclusion, adopting Conventional Commits in your Git projects not only streamlines the change tracking process, but also improves collaboration within development teams. By establishing a clear and structured format for commit messages, you facilitate understanding and long-term code maintenance. In addition, integration with Semantic Versioning and other automation tools can speed up and simplify the release of new versions, making your workflow more efficient and less error-prone.

If you want to know the pros and cons of using Git, you should read on this article.