3,678 reads

7 Rules for Writing a Good Commit Message

by Pragati VermaJune 27th, 2022

Too Long; Didn't Read

Well-written commit messages that follow a standard format can help you and the viewers of your codebase to easily decipher the context of any specific change, the modules it affected, and why was it required. In this article, we’ll outline a widely accepted yet simple yet simple format for good commit messages, based on the Semantic Commits style popularized by the AngularJS team. The semantics of a good commit message are: The type of commit type, the scope of the commit, the body and the description.

Companies Mentioned

featured image - 7 Rules for Writing a Good Commit Message

If you’re a developer, writing commit messages is a daily job for you. And if you have been working for a bit longer, you will know how a good commit message can be a savior in crucial instances and save you from the crunch.

In fact, good commit messages can make the striking difference between a well-maintained product, and a terrible one. Well-written commit messages that follow a standard format can help you and the viewers of your codebase to easily decipher the context of any specific change, the modules it affected, and why was it required.

In this article, we’ll outline a widely accepted yet simple format for good commit messages,

based on the Semantic Commits style popularized by the AngularJS team.

The semantics of a good commit message

Most of the developers don’t really think about their commits and commit messages as they start with development. Usually, the first few commits look as below:

Initialised the project

Initial commit

Added files

However, commits become really important when these are team projects. In that case, your project should be such that when you enter a new repository, you want to be able to see how the project has developed over time.

If you were to see commits like this, you would probably not be able to understand what happened without actually looking at the code for changes:

Fix the bug

Updated styles

Added new feature

However, if the commits looked like this, it would be much more helpful:

fix(blog): Imported posts formatted correctly with new styles 

feat(blog): Update styles to reflect new design 

feat(blog): Add blog feed to site

Let’s look at the 4 important parts of such semantic commits:

<type>(<scope>): <subject>

<body>

<footer>

The type of commit
The scope of the commit (optional, but often nice to have)
The actual content of the commit
An optional body, for more description. Good for larger commits
An optional footer

Type

You can use your own commit types, but here are the most common use cases:

feat: a new feature, or change to an existing feature.
fix: Fixing a bug or known issue in code.
test: Adding additional tests for existing features.
chore: Updating build tools, like webpack, gulp, ascripts, etc.
docs: Update to documentation like README, wiki, etc.

Scope

The scope of the commit can be kept as granular as required and is bound to change based on the complexity of the project. If you are starting off a project, it might not seem necessary at the beginning, although, it is highly recommended as it makes you think twice and harder about the changes that you are about to push.

Examples of probable scope values are as given below:

init
runner
watcher
config
web-server
proxy, etc.

Description

The description should be a summary of the changes in your commit in a single line. This could be used to determine the quality of your commit if you are not able to describe your changes in a single line, maybe you should step back and consider breaking down the commit into smaller pieces to make the changes more logical and self-contained.

Body (Optional)

A single line is good for a summary of the commit but there could be complex commits that might need some more explanation or description so that the reader can get more details and understand what you changed and why you changed it.

For example, if we had a commit with commit message and body, it would look as below:

feat(blog): Add blog feed to site

Add the markdown plugin, generate pages, and create blog template.

The footer can be used to reference issues that this commit might be related to or to list down breaking changes with the description of the change, justification, and migration notes.

For example:

feat(blog): Add blog feed to site

Add the markdown plugin, generate pages, and create blog template.

Closes #123, #245, #992

BREAKING CHANGE:

`port-runner` command line option has changed to `runner-port`, so that it is
consistent with the configuration file syntax.

To migrate your project, change all the commands, where you use `--port-runner`
to `--runner-port`.

7 Rules for Writing a Good Commit Message

Here are 7 important rules that you should keep in mind while writing your commit message:

The type and scope should always be written in lower case.
The commit message cannot be longer than 70 characters.
The commit body should be wrapped at 80 characters.
The scope can be empty if the changes are global or are difficult to assign to a single component. In that case, parentheses should be omitted.
Always use the imperative, and present tense to signify the change.
Do NOT include any secrets such as passwords or TLS keys in the message.
Avoid massive sizes. There is no practical limit to how much text may be stuffed into the commit body, however, a 100MB message would absolutely destroy performance.

Conclusion

Writing better commits will help you write better code as well. Simple practices as discussed above will help you to forge your mindset of self-documenting your projects by being aware and conscious of your commit messages.

This is all for this article, I hope you found it helpful. Keep reading!