Git Conventional Commits

Let’s talk about the principles of communicating with other developers through Git – also known as Conventional Commits!

Communicating with other developers through Git

Intro

Whenever you write code, it’s important to remember that machines are not the only ones who will read it in the future – there will also be other engineers, as well as the future you (who will have probably forgotten the exact implementation from like a year or two prior). Software development is a team effort, and therefore, it requires clear communication – especially when it comes to making changes.

One day, your team may switch over to a different messaging app, or your chat history may reach its limit after a while – either way, it’s very likely that a lot of the project-related messages will not be kept forever. However, if you use Git, you can be sure that all of your code changes, commits and accompanying notes will get saved no matter what. This is why a project’s Git repository can be considered its ultimate source of truth, while every cloned repository can represent a complete and decentralized backup of it. 

To have a better idea of how to use Git to its full potential, take a look at this Linux repository – as you can see, the commits there are basically equivalent to an email message that one may send when introducing various code changes. It’s hard to write good atomic commit messages, though. And, admittedly, it also takes some time to get used to working with Git according to its best practices. 

So, the question is: How to make sure that every team member follows these Conventional Commits guidelines? And how to remember to do it yourself? To which I present to you a pretty neat solution: linter :) 

Conventional Commits v1.0.0 standards

AutoGit (a short introduction to the tool can be found on the Noveo blog as well) helps development teams to adhere to the standards defined in Conventional Commits v1.0.0. It operates through Git hooks of your repository and, once linked, will enforce the use of best practices within any of your Git GUI tools.

For example, you will be encouraged to write commits in the following way (AutoGit won’t let you submit them unless they adhere to the set rules):

<type>(<optional scope>)(optional breaking change '!' char): <subject>
empty separator line
<optional body>
empty separator line
<optional footer key: footer key value>
<optional footer2 key: footer2 key value>

Usage example

docs: correct spelling of CHANGELOG

feat(api)!: send an email to the customer when a product is shipped

fix: prevent racing of requests

Introduce a request ID and a reference to the latest request. Dismiss
incoming responses other than the ones from the latest request.

Remove timeouts that were used to mitigate the racing issue but have now become obsolete.

Reviewed-by: Z
Refs: #123

Video instruction:

How does it benefit you?

1. It’s easier to review pull requests – be it your teammate’s code or your own.

  • Each line of code is easier to understand, one can clearly tell why it was added.

2. You can use git blame for each line of code in your Git file, in order to check who wrote it as well as the reason why it was done that way. 

  • You can access the commit linked to each line, and (hopefully) find a good description / message explaining why this particular change was made :)
$ git blame main.go
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100  1) /*
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100  2) Copyright © 2022 NAME HERE <EMAIL ADDRESS>
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100  3) */
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100  4) package main
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100  5)
d4745237 (dd84ai 2023-12-10 00:09:35 +0100  6) import (
d4745237 (dd84ai 2023-12-10 00:09:35 +0100  7)  "autogit/interface_cli"
d4745237 (dd84ai 2023-12-10 00:09:35 +0100  8) )
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100  9)
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100 10) func main() {
def7cc5c (dd84ai 2023-10-21 23:30:37 +0200 11)  interface_cli.Execute()
^3e43b5c (dd84ai 2022-12-10 19:54:42 +0100 12) }

$ git log 3e43b5c
commit 3e43b5c006406b75afc8ca083262a71c462fd9d0
Author: dd84ai <dd84ai@gmail.com>
Date:   Sat Dec 10 19:54:42 2022 +0100

    chore: init project with GPL license

3. You can have comprehensive changelogs generated for each product release!

  • AutoGit already has this feature embedded, but you can also use any other tool suited for parsing Git Conventional Commits. 

Example of a generated changelog:

Example of a generated changelog

4. Having neatly organized Git commits, tags, releases and changelogs will make your repository look as professional as ever ;)

But, you may ask yourself, how to enforce this for all of the developers who use your project’s repository? The answer is simple: run a CI pipeline with AutoGit for every push and pull request! 

What makes AutoGit different?

It’s true that there are many tools for working with Conventional Commits, so why should you use AutoGit? Here’s a brief rundown of things that make it stand out among other solutions: 

  • It was created with CI usage in mind, so it’s very easy to incorporate it into any kind of CI tools – just make sure to clone the repository with the history of your tags and commits :)
  • Since it is a compiled Golang binary file, there’s no need for you to install Node.js of any specific version, or any other heavy interpreter for that matter – AutoGit can successfully run on its own, either in CI or on a local dev machine.
  • It also includes a built-in Git, which means that you don’t have to install Git in order for the tool to work correctly.
  • As a Golang-based solution, it can handle the addition of a lot of extra features :) 
  • AutoGit was developed with the idea of its being as automated as possible, and operating as a CLI tool that can help you to release products in a more professional way. 
  • It can work with all of the defaults out-of-the-box, but it can also be fully tailored to your needs – configure the settings using the autogit.yml file, and you’re good to go! 
  • And finally, with its operating through Git hooks, the solution is compatible with pretty much every Git GUI tool and IDE there is. 

Recap

  • We reinforced the idea that communication is important – your code, as well as the changes you make to it, should be clear to other developers (including your own self who’ll be working on the project in a year or two).
  • Git serves as the ultimate source of truth regarding any project, it will stay with your team for as long as the product exists. 
  • To turn Git commits into an organized, easily readable history of project changes, make sure to use Conventional Commits and enforce them with the help of linters.
  • The history of your Conventional Commits can also be used to generate nice and comprehensive changelogs for every product release.

And that’s it! In case you want to learn more, or are ready to get started with your AutoGit adventure, here’s the link to the tool :)