Understanding the importance of semantic commits

Article cover

At the bank I currently work at, we are developing a document with good practices that will be followed by all the bank's devs, and one of the items in that document is Semantic Commits, which is a simple practice that we should use not only in corporations, but also in personal projects.

I believe that there are still many programmers who are unaware of this good practice, and my intention with this article is precisely to increase your knowledge, and with that, you can see the full potential behind the use of these commits, for example : show a company you want to apply for, that their projects have good commits, even before working on work teams.

What are Semantic Commits?

According to the Convetional Commits documentation, Semantic Commits are a simple convention to be used in commit messages. This convention defines a set of rules for creating an explicit commit history, which facilitates the creation of automated tools.

Why perform this type of commit?

In addition to what is mentioned in the documentation, these commits will help you and your team to easily understand what changes were made to the piece of code that was committed.

This identification occurs through a word that identifies whether that commit made is a code change, package update, documentation, visual change, test...

To get an idea of how important they are, the Karma test library uses the semantic commit pattern as a message criterion for generating the change log. To view Karma documentation just click here.

How to perform a Semantic Commit?

The base structure of a semantic commit or "skeleton" is:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Type and Description

The semantic commit has the structural elements below (types), which inform the intent of your commit to the user of your code.

So, imagining that we are in a work environment, and I am committing my activities, I have to be descriptive and succinct at the same time, for anyone who is going to review my code or in the future is messing with code snippets that I created or changed, can briefly understand what I accomplished by reading my commit.

Types:

  • fix - Commits of the fix type indicate that your committed code snippet is solving a problem (bug fix), and is related to the PATCH of the semantic versioning, that is, to the last number that involves the semantic versioning standard SEMVER. Imagining a version number 2.3.0, the zero is the PATCH.
  • feat - Commits of type feat indicate that your code snippet is including a new feature. It relates to the MINOR of semantic versioning. Using the above version as an example, MINOR is the number 3.
  • docs - Commits of the type docs indicate that there have been changes in the documentation, for example in the Readme of your repository or in the CHANGELOG. (Does not include code changes)
  • style - Commits of type style indicate that there were changes related to code formatting, semicolons, trailing spaces, lint... (Does not include code changes)
  • refactor - Commits of the type refactor refer to changes due to refactorings that do not change its functionality, such as, for example, a change in the format of how a certain part of the screen is processed, but which maintained the same functionality, or performance improvements due to a code review.
  • build - Commits of type build are used when making changes to build files and dependencies, or when generating build files.
  • test - Commits of type test are used when changes are made to tests, either by creating, modifying or deleting tests, which can be unitary, E2E...
  • chore - Commits of the type chore indicate updates to build tasks, admin settings, installing new libraries, adding a package to gitignore... (Does not include code changes)
  • BREAKING CHANGE - Commits that have the text BREAKING CHANGE at the beginning of the optional body or in the optional footer, indicate that the modification being carried out in the commit, has a modification that can break the compatibility between items of your application, API, such as upgrading the Expo version, or changing environment variables. It relates to the MAJOR of the semantic versioning, which is equivalent to the first versioning number, using this version as an example 2.3.0, it would be the number 2.

Observation: When using BREAKING CHANGE it is mandatory to inform a description, which should contain what was changed in the API for example. In addition, it is indicated that the type is accompanied by a ! to draw attention to the compatibility break.

  • Semantic commit that includes the BREAKING CHANGE in addition to the ! to draw attention to the compatibility break:
cry!: removing Node 6 from the test matrix

BREAKING CHANGE: removing Node 6 reaching end of life in April
  • Semantic commit with just type and description:
docs: improving CHANGELOG description

Body

The body, as mentioned in the "semantic commit skeleton" is optional. It is indicated to use it when the details of your commit will be greater than 7 words.

  • Semantic commit with body:
feat: added new frontend folder structure

- A change was made in the entire structure of the pages of the frontend project,
because now we will use the Atomic Design model

Scope

The scope of the commit is optional, and it is with it that we will inform which part of the code was modified. It can be the name of a component, a certain API property or the name of the API, a function...

  • Semantic commit with scope and body
fix(ProductApi): removing variable from API path and adjusting loggers

- The previous path had unnecessary variables and not used by any
consumer

Baseboard

The footer, as well as the scope and description, are optional to be informed. It usually contains an issue, id or activity tasks, which were used to create/alter this committed code snippet.

  • Semantic commit with scope, body and footer
fix: fix small typos in the code

see ticket for details on fixed typos

originated from issue JD#12

In addition to the benefits mentioned above, I believe that Semantic Commit can demonstrate that your developer profile is reaching another level, and that in addition to introducing good practices in your code, you are concerned about inserting good practices in your commits.

These best practices in the commit will help you when you have to solve a problem and/or when a coworker is working on that piece of code made by you, and will be able to understand just by looking at what was put in the commit.

I hope you liked today's tip, because the focus of the articles is to make you a better dev!