DEV Community

Jonathan Irvin
Jonathan Irvin

Posted on

Clean Conventional Commits

Let’s face it, Git is a chore. It’s about as exciting as cold oatmeal. However, when used properly, it can save millions™.

5 Sanity Checks For Your Commits

Frequent

The more often you commit, the better you track your changes and have the ability to revert if needed. Frequent and small commits are easily merged without conflict. It’s like saving a game, only better.

Atomic

Atoms are small and your commits should be, too. Don’t cram 8 hours of work into a single commit. Atomicity should also apply to your commits. Everything that’s in the commit should be related. This allows you to easily revert without undoing unrelated changes.

Descriptive

What’s the last thing you need when moving? Mislabeled boxes or boxes with incorrect labels. Commits should be written in the imperative sense. They should describe what they DO, not what they DID.

Decentralized

Git, in its design, allows complete shared “ledgers” of changes between each clone of the repo. The entire history of the project is kept on every machine. As such, don’t let commits stay on your local machine. If you have a remote repo, keep your code published somewhere else. You never know when your laptop will cache on fire, become self-aware, or worse.

Immutable

Git gives you the “keys to the kingdom” and allows you to do any number of destructive operations to your repo. I’ve seen bad merges go down and months of work lost from one wrong move. As such, treat your commits as immutable. Once they have been written, they are sealed for all eternity. If you need to make changes, revert a commit and make a proper change.

What are "Conventional" commits?

As Git gives you all the freedom in the world to name your branches and commits whatever you want, it’s a good idea to have a common convention for how those commit labels are authored.

Here’s the td;lr (Summary)

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
Enter fullscreen mode Exit fullscreen mode

Yes, commits can be multi-line and are written like emails. 99% of the time, however, you will be focusing on the first line.

Bare minimum

<type>[optional scope]: <description>

image

Scared? Don't be.

I know what you're thinking...

image

Luckily there are tools that help this process go super smooth.

image

Give me the deets already.

Type (Required) (Spec)

These categorize a commit and tell you what kind of change this is. Here are examples:

  • feat - for new features
  • fix - for defects or bugs
  • chore - for changes that don’t alter the source, but necessary
  • ci - for ci pipeline changes
  • docs - for documentation changes
  • perf - for performance enhancements
  • refactor - for refactors; altering the code, but not changing functionality
  • revert - reverting changes
  • style - for cosmetic changes
  • test - for unit tests

Scope (Optional) (Spec)

Scope allows you to box your commit into a specific feature, file, or sub-set of the application.

fix(Navigation): change Loggin to Login

chore(deps): upgrade Jest to v24.5.7
Enter fullscreen mode Exit fullscreen mode

Body (Optional) (Spec)

Just like the body of an email, if you want to add more of a description to your commit, you can do so below the first line.

Note: If the commit contains a BREAKING CHANGE, this goes in the body of the commit.

feat(Authentication): update cipher for better security

 BREAKING CHANGE all security keys will need to be regenerated and deployed.
Enter fullscreen mode Exit fullscreen mode

Footer (Optional) (Spec)

Footers are optional, but allow for ticket references to be made in the commit without clogging up the commit subject line. The follow a specific format:

..."each footer MUST consist of a word token, followed by either a : or # separator, followed by a string value."
Conventional Commits

There are several tools that will parse commit messages and automatically make links to tickets.

refactor(Header): correct minor typos in code

see the issue for details

Refs: JIRA-9999
Enter fullscreen mode Exit fullscreen mode

image

FAQ (source)

How should I deal with commit messages in the initial development phase?

Proceed as if you’ve already released the product. Typically somebody, even if it’s your fellow software developers, is using your software. They’ll want to know what’s fixed, what breaks etc.

Are the types in the commit title uppercase or lowercase?

Any casing may be used, but it’s best to be consistent.

Although, more often than not, lowercase is used.

What do I do if the commit conforms to more than one of the commit types?

Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs.

Doesn’t this discourage rapid development and fast iteration?

It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors.

Top comments (9)

Collapse
 
seokjeon profile image
Se-ok Jeon

Thx for this! This is really what I wanted. Helped A LOT.
Can I translate in Korean this article? If you don't mind, I wanna share this awesome information in Korean. Surely, There will be a link directing to this original one.

Collapse
 
ashoutinthevoid profile image
Full Name • Edited

The spec and all related info are already available, translated, on the conventional commits website. Regardless of what the article's author responds, you can share that in Korean with no added effort.

Collapse
 
seokjeon profile image
Se-ok Jeon

But you know that there are differences in form of the contents.

Thread Thread
 
ashoutinthevoid profile image
Full Name • Edited

I cannot offer an opinion on the existing Korean translation, as I don't speak the language.

If we're talking about the english version, Im not of the opinion that this article makes any substantive addition beyond memes.

In any case, I hope you find what you need and make a convincing argument to your intended audience.

Collapse
 
kigiri profile image
Clément

Good principles !

I would like to point out that it is VERY HARD to loose work with git.

Everything is saved, even after a bad manipulation, i've never not been able to find the HEAD of my a working branch somewhere.

I was afraid of rebase for a long time, I now find frequent rebase and working with a more linear history much easier and don't have big issue with merges anymore.

if it ever happens to you again, trust in git and dig in the reflog :)

Collapse
 
mbrookes profile image
Matt

"chore" is just so negative though. How about "core" instead?

Collapse
 
offendingcommit profile image
Jonathan Irvin

Ooooo, I kinda like this, but chore implies a necessary, but boring task. It doesn't add anything or fix anything. It just is.

"core" to me seems essential, but could be confused with adding a feature or refactoring critical code.

Collapse
 
ben profile image
Ben Halpern

Great post

Collapse
 
offendingcommit profile image
Jonathan Irvin

Good to see you, @ben ! It's been a while since I've posted. So much has changed. I should write about it!