Conventional Commits – Adding meaning to your git commit messages

Recently I saw came across a link to a git specification known as “Conventional Commits”. I’ll discuss my opinions of it in this short post.

What is it?

Recently I saw came across a link to a git specification known as “Conventional Commits”.

A specification for adding human and machine readable meaning to commit messages

https://www.conventionalcommits.org/en/v1.0.0/

Upon taking a glance through the specification I liked the idea for having commits store more useful information. We’ve all seen git commit messages like “a fix” or “fixes bug” but they vaguely tell you what is in it. This lacks detail about why the change was made though.

Structuring Conventional Commits?

The conventional commits specification aims to improve this by providing a simple set of rules to commit messages that explain what changed. When looking through a repository, you often can see a list of vague commit messages. These state what has changed but not why they have and what it means to other users.

You can find an example of the basic structure for a conventional commit below. In short you should have a type of commit fix or feat (but these are optional) which correlate to Patch and Minor changes in Semantic Versioning (Semver). Then an optional scope which “MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser):”.

The short description covers a change that has been made e.g. “array parsing issue when multiple spaces were contained in string.”.

Describing the change in the optional body part of a conventional commit is where is see the key benefit. Putting a reason for making the change is extremely useful when collaborating on a project.

So this is all great but where else are conventional commit messages useful?

Why use them?

Ultimately the thing that still excites me about being a developer is the satisfaction with automating a task.

One of the best uses I have found for Conventional Commits is with this PHP Library: https://github.com/marcocesarato/php-conventional-changelog

Essentially this library will go through your git repository and build up a changelog based on the conventional commits. The library can handle things like automatically bumping your version numbers and generating a dynamic changelog. Paired with tools like Github actions and gitlab pipelines this is incredibly useful to automate releases of your libraries. The best part about the Conventional Commit workflow is it’s ability to support automation of various tasks.

I am currently using it for a plugin I recently built in Craft. So far it has helped me save a bunch of time keeping my changelog up to date and managing my releases.

What do you think about conventional commits, how do you manage your repositories and versioning. Drop a comment below to let me know, I’d love to hear and discuss other approaches so we can all learn from each other.

Leave a Reply

Your email address will not be published. Required fields are marked *