Commit Guidelines

A specification for adding human-readable meaning to commit messages

Introduction: Why good commit messages matter

If you browse the log of your random Git repository, you will probably find its commit messages are more or less a mess. Somewhat like the ones shown in the image above.

Compare that with these -

njsf382 chore: update cron schedule rate
8294sdm feat: add docker-compose for service containers
2903jsd fix(eslint): allow template literals

Which would you rather read & Why follow a guideline ?

The former varies in length and form; the latter is concise and consistent.

The contributors to a repository know that a well-crafted Git commit message is the best way to communicate context about a change to fellow developers (and indeed to their future selves). A diff will tell you what changed, but only the commit message can properly tell you why. Someone rightly said:

Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

If you haven’t given much thought to what makes a great Git commit message, it may be the case that you haven’t spent much time using git log and related tools. There is a vicious cycle here: because the commit history is unstructured and inconsistent, one doesn’t spend much time using or taking care of it. And because it doesn’t get used or taken care of, it remains unstructured and inconsistent.

But a well-cared for log is a beautiful and useful thing. git blame, revert, rebase, log, short log and other sub-commands come to life. Reviewing others’ commits and pull requests becomes something worth doing, and suddenly can be done independently. Understanding why something happened months or years ago becomes not only possible, but efficient.

A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.

This guide address just the most basic element of keeping a healthy commit history: how to write an individual commit message.

The commit message should be structured as follows:

<type>[optional scope]: <subject>

Types

• feat Commits, that adds a new feature
• fix Commits, that fixes a bug
• refactor Commits, that rewrite/restructure your code, however does not change any behavior
• perf Commits are special refactor commits, that improves performance
• style Commits, that do not affect the meaning (white-space, formatting, missing semicolons, etc.)
• test Commits, that add missing tests or correcting existing tests
• docs Commits, that affect documentation only
• build Commits, that affect build components like build tool, ci pipeline, dependencies, project version, …
• ops Commits, that affect operational components like infrastructure, deployment, backup, recovery, …
• chore Miscellaneous commits e.g., modifying .gitignore

Scopes

The scope provides additional contextual information.

• Is an optional part of the format
• Allowed Scopes depends on the specific project
• Don’t use issue identifiers as scopes

Subject

The subject contains a succinct description of the change.

• Is a mandatory part of the format
• Use the imperative, present tense: “change” not “changed” nor “changes”
• Don’t capitalize the first letter
• No dot (.) at the end

Examples

feat(shopping cart): add the amazing button

feat: remove ticket list endpoint

fix: add missing parameter to service call

build (release): bump version to 1.0.0

build: update dependencies

refactor: implement calculation method as recursion

style: remove empty line 

revert: refactor: implement calculation method as recursion