Conventional commits

Introduction

Writing good git commit messages is ultimately a matter of personal preference. However, there are conventions that have tooling support and make them easier for others to read. This blog post will look at two of them: conventional commits and gitmoji. Furthermore, we will see how to automate releases in GitHub using either.

Personal journey

Early on, I tried to make a scheme for my subversion commit messages. That quickly became mercurial before the industry seemed to land on git. The problem was the same: how do I make commit messages that convey the intent of the change without badly summarizing what can already be read in the code changes? I started to preface the messages with the following:

• bug: {what is the bug}?
• feature: {what is the new feature}?

I was pretty happy with it. However, I needed to explain the format to any new or existing team members.

Then, I started working on a project with a team member that mentioned conventional commits.

Conventional commits

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides a set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of. The structure of a Conventional Commit message typically includes a type (e.g., feat, fix, docs), an optional scope, and a description. This facilitates the automatic generation of changelogs and the determination of semantic versioning. Here is an example of a conventional commit message:

feat[tax-calculation]: added tax as variable

As we see, it's quite the same as my homemade convention. However, now I have a specification to follow and send to any other developer who might be wondering about the format.

Gitmoji

Gitmoji is another convention for git commit messages that use emojis instead of text like feat, fix, or docs. Each emoji has a specific meaning, making it easy to visually scan the commit history. For example, 🐛 represents bug fixes, ✨ represents new features, and 📝 represents documentation updates. You can find the complete list at https://gitmoji.dev/.

I use gitmoji on my personal projects with a git hook that I install using the gitmoji-cli tool. The hook takes me through a short, interactive guide in the terminal, making sure my commit message is according to the specification.

Either conventional commits or gitmoji fulfills the same purpose: a standardized messaging format that enables, among other things, release automation.

Release automation

Now that we have a standardized way of writing these commit messages, we can automate the release process while using semantic versioning, for example. I have been using the semantic-release project and GitHub actions. For every commit into main, the GitHub action reads all of the commits since the last release, bumps the release number based on a convention, and creates a GitHub release following the semantic versioning scheme. Take a look at my Neovim repo, where I use the setup: https://github.com/fredrkl/nvimsetup.

The GitHub action uses a .releaserc file where you can specify the release process. Mine looks like the following for gitmoji:

{
  "branches": ["main"],
  "plugins": [
    "semantic-release-gitmoji",
    "@semantic-release/changelog",
    "@semantic-release/github",
    "@semantic-release/git",
    [
      "@semantic-release/exec",
      {
        "successCmd": "echo 'nextRelease.version=${nextRelease.version}' >> $GITHUB_ENV"
      }
    ]
  ]
}

Look at the release.yml gh workflow file for an example of how to trigger and run the release generation. The project's CHANGELOG is changed by default to reflect any new release.

Summary

This post explored different approaches to writing meaningful git-commit messages. We looked at two main conventions: Conventional Commits, which provide a structured format with types and scopes, and Gitmoji, which uses emojis to represent different types of changes visually. Both approaches aim to make commit histories more readable and maintainable.

We also discussed how standardized commit messages can enable automation in the release process through tools like semantic release. This automation can handle version bumping and changelog generation based on commit conventions, streamlining the release workflow.

Whether you choose Conventional Commits or Gitmoji, adopting a consistent commit message convention can significantly improve project maintainability and enable powerful automation capabilities.