Creating A Detailed Commit History With Conventional Commits

Have you ever looked at your git log to get a sense of a branch's status only to be met with a wall of ticket numbers? Or have you had to determine a version for your upcoming release while manually maintaining a changelog? One of the best things we can do for our future selves is to write good commit messages. They allow us to keep track of changes and communicate the status of the repository to other team members. A popular approach is to add ticket numbers or other identifiers to the commit message. That will help us eventually track down what is happening in a repository but that kind of information is really meant for your project and issue tracking integration. Alternatively, adding a detailed commit message is also helpful but reduces our ability to scan the log to get our overview if too verbose. To make these tasks easier on ourselves we can follow a few simple rules.

Below is the Conventional Commit format and structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Though this looks like it would make commits more complicated the only required pieces of information are the type and description. The type describes the intent of the changed code and the description summarizes the change. There are even specifications for formatting descriptions but that isn’t mission-critical to our current discussion. At the end of the day, we are just labeling or categorizing our commit. Is it fixing a bug? Use the fix type. Does this commit include a new feature? Then use the feat type. Using these two types alone already adds a layer of valuable information to our commit messages. If you’d like to detail what part of the application or system is being updated, reference that section in the scope slot. Not only will you quickly add more information to the commit message but tools like Lerna can use this content to track changes of packages in a monorepo. The body stores a more detailed summary of our changes and the footer is a great spot to call out related tickets, references, and/or acknowledgments.

I know what you’re thinking. I’m already following guidelines and specifications to complete my functional code, why should I use another one just to write commits! There is a bit of a learning curve and adjustment, at least there was for me, when I started using this convention. I suggest starting by just adding the feat or fix type to the start of your commit messages. Those 2 types should meet the majority of our use cases. Then start sprinkling in others like docs, test, and chore if the production code isn’t changing. There are also great tools and extensions we can use to help us write commits using this convention. Here are a few extensions for our IDEs:

Visual Studio Code

● Conventional Commits

● Commitizen Support

IntelliJ (JetBrains)

● Conventional Commit

There are also command-line tools like this one by commitizen that help us generate a commit message through a guided workflow and a commit linter to make sure the project adheres to the specification with something like husky and commit hooks.