GIT - Semantic Commits

What are “semantic commits” or “conventional commits”

Semantic Commits, also known as conventional commits, are the best way to document your implementation of applications, as you check context to the management of change of your source code. Semantic commits are considered good practice in the use of GIT as much as other VCs (code versioning systems).

Why to use semantic commits

You should write in a GIT commit message not only what you have done, but also specifying WHY you have done that.

This brings semantic to the commit message, and will make it easier to track changes over time, and also can be useful in troubleshooting issues.

Examples:

❌ add endpoint ✅ add endpoint to enable users to download purchase history

❌ update dependencies ✅ update dependencies to address security vulnerabilities

❌ fix bug ✅ fix bug to solve inconsistent rendering on mobile devices

Clear and descriptive commit messages are a part of internal software quality. So, to be semantic in commits you can write the messages giving the context of WHY the change has be done, and also standardize the form of the commit using conventional commits.

Next we gonna anderstand the problem, then take a look on how to use conventional commit.

The problem when not using semantic commits

Write messages from uncommonly, such as Task Done or Bug Fixed do not help in the maintenance of code and the evolutionary history of the system.

Analyze commit’s message history below:

commit e71fcf2022b6135e18777bdc58c2ac3180202ec7
Author: mazerdev
Date: Tue Apr 24 01:25:48 2021 +1000
Extract information

commit d1952883b05b685f2d22e4c41b4fbc4362fd6bd0
Author: mazerdev
Date: Mon Apr 23 22:16:50 2021 +1000
[WIP] integration

commit 74b8920d96e3e09d5cd958ffa369a0e3c86a6851
Author: mazerdev
Date: Mon Apr 23 21:09:11 2021 +1000
Task 25 delivered

commit b02255b25eed57c7595504c66233d5ee3024190c
Author: mazerdev
Date: Mon Apr 23 18:32:40 2021 +1000
[WIP] Widget Search

The thinking of those who write the commits like this would be: I will never worry about using Commit Body.

When you are working on a company where by creating a PR, or doing code review, it is not a common task, no one will bother to ask you to write a good Commit message.

However, this changes when you start working with teams with a good engineering culture, where to write a message from explicit and Semantic Commit, defines the acceptance and quality of your deliveries.

Looking again at the messages of the commits above, do you know why they are “flaws”? Just ask them some questions:

Extract information: Where are you extracting information? What is the format of extraction?What is the source?
Integration: What, which business rule, integrating with which system, external service?
Task 25 Delivered: Will make me open the demand manager, which I don’t even know if it is the same used when you finished the task?
Search on widgets: Which Widget from which screen?Will I have to read your code to try to identify?

The solution using semantic commits

Contributors of project repositories with excellence in their management know that a well designed Git Commit message is the best way to communicate the context about a change to other developers (and in fact to themselves in the future). A diff will tell you what has changed, but only the confirmation message can say why. Peter Hutterer explains this point well:

Restoring the context of a code passage is a waste.We cannot avoid it completely, so our efforts should be to reduce it [as much] as possible. Confirmation messages can do just that and, as a result, A Commit message shows if a developer is a good collaborator.

I would complement with: If a developer works well in team

The solution therefore is to write Commit messages to quality describe the context of implementation. Messages that have contextual meaning, that is, semantically well written messages.

Therefore semantic commites are our solution, and if we combine semantics with a standardized structure for the team, we can guarantee high quality gains in the commites.And this is the proposal of the conventional Committs.

Seven directives for a semantic message from Commit do Git

Just know that: all this already was told before.

These seven guidelines serve as a primary guide to write quality semantic commits:

Separate the subject from the body with a blank line
Limit the subject line to 50 characters
Put the subject line in a capital
Do not finish the subject line with a point
Use imperative mode on the subject line
Wrap the body in 72 characters
Use the body to explain what and why - do not explain how, that is the code

The guidelines must be applied to a format, a pre-established convention, read the proposal for conventional conventional Committs, with some practical and didactic examples.

Where to start?

Most programming languages have well established conventions about what constitutes their idiomatic style, that is, nomenclature, formatting and so on.

There are variations of these conventions, but most developers agree that choosing one and fulfilling it is much better than the chaos that comes when everyone makes their own shared code choices.

It is important to understand that the approach of a team for your LOG of Commit should be no different.

To create a useful review history, teams must first agree with a Commit message convention that establishes at least three things:

Style: Marking syntax, breach of margins, grammar, capitalization, punctuation.Remove these things, eliminate conjectures and make everything as simple as possible.The end result will be a remarkably consistent record that is not just a pleasure to read, but it is actually read regularly.
Contents: What kind of information should contain the body of a commit message (if any)? What should not contain?
Metadata: How the IDs of tracking of Issues and Tasks, Pull ids and Merge Requests, etc. must be referenced?

Fortunately, as for programming languages, there are well established conventions about how a Git Commit message should be written to be idiom.

So you and your team need not reinvent anything.Just follow the seven rules described in this article and standardize the format you and your team will be on the right track to compromise (ComMiting 😀) as the professional quality of the project.

Conventional Commits for Semantic Commit

The specification defined by Conventional Committs offers a simple convention to use in Commit messages.

It defines a set of rules for creating a history of explicit commit, which facilitates the creation of automated tools based on the specification.

Explicit instead of implicit - as a friend says, “The obvious should be said”

This convention aligns with Semver - semantic versioning, describing the resources, corrections and modifications that break compatibility, all in Commit’s messages.

The Commit message must be structured as follows:

<type>[optional scope]: <description>

[optional body]

[Optional footer]

Let’s understand what each information block and each structural element means and how it should be filled.

Type

The subject of the Commit message should be pre-made with a type to communicate Commit’s intention:

build: this commit type specify changes that affect system compilation or is related to external dependencies (for example: composer, maven, gulp, broccoli, npm)
chore: this commit type are used when changes occur in updates that do not impact buildings or the product, for example: grunt tasks, .gitignore.
ci: this commit type describe changes to CI configuration files and scripts - Continuous Integration (affect for example: Travis, Circle, BrowserStack, SauceLabs, Github Actions, Gitlab CI)
docs: this commit type only have changes in documentation, as README or docblocks.
feat: this commit type includes a new feature in its code base (this correlates with MINOR of semantic version, or MAJOR if you enter a compatibility break with the previous version - See Breaking Chance later in this article).
fix: this commit type solves a problem, a mistake, a bug in its code base (this correlates with PATCH of semantic version).
perf: this commit type indicate changes in code that improve application performance.
refactor or refact: this commit type should be used when a code change does not correct a system bug or add a new feature to the application.
style: this commit type identifies changes that do not affect the “meaning” of the code, change the style of the code, such as: blank space, identification, formatting, lack of point and comma, etc.
test: this commit type describes the addition of missing tests, new specific tests or existing testing.

Body

The body of the commit message should contain complementary information regarding the type, scope and description already defined in commit’s “title”.

Don’t use the body of the message to demonstrate how the change on the code was made, but to contextualize “why”, in relation to the business rule, that implementation was made.

BREAKING CHANGE: a Commit that contains the optional footer text BREAKING CHANGE:, or contains the symbol ! after type/scope, introduces a modification that breaks the compatibility of the application, API or LIB (this correlates with MAJOR of semantic version). A Breaking Change can be part of any type.
Other footers different from BREAKING CHANGE: <description> can be provided and follow the convention that looks like git trailer format.

Note that these additional types are not required by the specification of the Conventional Committs and have no implicit effect on semantic version (unless they include a Breaking Change). A scope can be provided to the commit type to provide additional contextual information and is contained in parentheses, for example feat(parser): adds the ability to interpret arrays. Therefore when using scopes the footers in general are not required.

Why use Conventional Committs

With the use of Conventional Committs, some advantages and optimizations can be achieved in your project, benefiting the entire team:

Better communication

Through the conventional commits it is possible to communicate the nature of changes to teammates, the public and other stakeholders of the project.

With higher quality communication, it becomes easier to contribute other people to their projects, allowing them to explore a better structured commit history.

Even some of these benefits can be achieved automating tasks:

Automated Creation of CHANGELOGS.

Maintaining updated documentation, besides consuming a lot of time, is a task that requires discipline. The CHANGELOG document is one of these documentary components, necessary but difficult to maintain.

Using Conventional Commits is possible to automate this task and deliver higher quality with change reports to each system deploy, increasing visibility to the team and sponsors.

Some of the tools that can be used are:

In addition to automating CHANGELOG Report, you can automatically determine changes in semantic version (based on the types of commits).

Automate processes

In addition to assisting communication, and allowing to automate related tasks, it is also possible to fire Build and Deploy processes with the use of conventional commits.

How to use conventional commites in everyday

When using project management tools such as Jira, Gitlab, Github or another one that job management and work demands, if you put the ticket number (Issue) in your Commit message, Jira or Github can detect it automatically and incorporate a direct link to the card you are working on.

This works well with Conventional Commit, as it is possible to put the jira ticket number (for example) in the of the message.

type(<jira/github number>): commit title

How about a real example:

fix(#331): Changes the default payment URL

The standard payment URL has changed service X, the change corrects the break by calling the API.

Final considerations

The use of Semant Committs through Conventional Committs brings high quality in tracking, traceability and knowledge sharing in the software development process, both for soil and team development.

Be sure to start your practice and incorporate in your daily life, the more you practice writing of high semantics messages, the faster the quality of the project increases.