DEV Community

Cover image for How I write Commits like a pro
phukon
phukon

Posted on • Updated on

How I write Commits like a pro

Crafting effective commit messages is a hallmark of experienced developers. Embracing the Conventional Commits specification stands as a beacon for structuring commit messages. It’s not just a guideline; it’s a pathway to a clearer commit history that harmonizes with Semantic Versioning (SemVer).

What are Conventional Commits?

Conventional Commits offer a lightweight yet powerful framework for organizing commit messages. By categorizing changes into distinct types like features, fixes, and breaking changes, it sets a gold standard for clarity and consistency and aligns with Semantic Versioning (SemVer) by categorizing changes into features, fixes, and breaking changes.

The Anatomy of a Great Commit Message

When making commits, please use the conventional commit format, which typically follows the pattern of <type>: <description>.

A commit message should follow this structure:



<type>[optional scope]: <description>
[optional body]
[optional footer(s)]


Enter fullscreen mode Exit fullscreen mode

type: type of commit

scope: Short description of a section of the codebase enclosed in parenthesis followed by a colon and a space. Messages tend to be in the present and imperative.

description: Short description of the code changes

body: A longer description of the commit, providing additional context about the changes.
Must be placed one empty line after the description.

footer: Fixes issue #3 //example
The footer should only contain additional issue references about the changes.

Examples:

A commit I made to solve an issue.
Image description



feat(homepage): Add carousel feature to showcase testimonials

Implemented a carousel component on the homepage
Added client testimonials section for improved user engagement

Fixes #12


Enter fullscreen mode Exit fullscreen mode

More examples:

  • feat: Add new rating component
  • fix: Resolve issue with city search feature
  • docs: Update README with new contribution guidelines

Types of Commits

In addition to the classic fixand feat, we've got a whole buffet of commit types. It's like choosing toppings for your commit pizza:

  • build: Changes related to build processes or tools.
  • chore: Regular maintenance or administrative tasks.
  • ci: Updates to the continuous integration setup.
  • docs: Documentation-related changes.
  • style: Changes that do not affect the code’s functionality (e.g., formatting).
  • refactor: Code modifications without changing its behavior.
  • perf: Performance improvements.
  • test: Adding or modifying tests.

You can use these types to categorize your commits according to their nature. This helps maintain consistency in commit messages and aids in better organization of changes in the project history.

Footnote

For more information on Conventional Commits, visit Conventional Commits Specification.

Top comments (40)

Collapse
 
theashraf profile image
Abdelrahman Ashraf

Thanks for sharing

I use this tool: github.com/streamich/git-cz, which is a CLI-guided tool to create awesome commit messages as well.

Collapse
 
pavlosisaris profile image
Paul Isaris

Very cool! Thanks for sharing!

Collapse
 
phukon profile image
phukon

this is so cool!

Collapse
 
donut87 profile image
Christian Baer

While the intent is good and for the most part this guideline is ok, I really do not like commit messages tell me what was done to the code. I can see that, when I look at the code. I want to know why this was changed. So please do not tell me, that you "changed the build process". I can see that. What I cannot see, by looking at the code is why we changed the build process. A message like "build process was taking 20 min, now takes 2" with some explanation in the body is way better. "Resolve issue with search feature" is also something, that I can see by git show --name-only pretty quickly. But what was the issue?
"Add a new rating component". Yes... I can see that you inserted a new file in folder 'rating-components' that pretty much gave it away already. What rating component? Is it replacing the old one? Is it country specific? Gender specific? (Don't flame me for this, that shit happens in real life)

Botton line: Having a what is better than nothing (aka 'Did stuff'), but having a why is even better.
Why > What > Nothing.

Collapse
 
shenoudafawzy profile image
Shenouda Fawzy

Good day Christian Baer, what if the product is +100K line of code, don't you think that 'What' is the most important thing in the commit message than 'why', otherwise whoever reading/reviewing might get lost.
For the 'Why' it's even more important, cause without it then it's pointless to do write whatever code is, but in context of the message commit, I prefer 'what' over than 'why' which could be described on the issue/ticket itself. And leave the commit message to 'what' is actually changed to achieve the task (that has the why)

Collapse
 
xtofl profile image
xtofl

Funny sidemark: we currently use a template that features both why and how:

feat(SF-123): Show SNP percentages

Why? because assay designers need to estimate how often
the base occurs in each designed primer

How? add 'frequencies' member to HTMLChar, and use it in
the dialog box.
Enter fullscreen mode Exit fullscreen mode
Collapse
 
the_olusolar profile image
Solar

In my opinion, I think one can use the what as description and then include the why in the body of the commit. that way, both are fulfilled.

Collapse
 
thesnowmanndev profile image
Kyle Martin

Why would one pull request encompass 100k+ lines of code exactly?

Collapse
 
borzoomv profile image
Borzoo Moazami

Nice post, thanks for sharing.
Also I think it worth to think about what we've done when trying to write the description.

For example there are times when we fix a bug by changing something in x.ts file.

Appropriate commit message would describe what issue we have resolved not what we changed in x.ts.

BTW thats my idea and I had better experience during reviewing more meaningful commits and don't know if it is a rule or something.

Thank you again.

Collapse
 
aneshodza profile image
anes

Also important to mention: Commit messages tend to be in the present and imperative.
E.g: Implement search feature.

Collapse
 
emamut profile image
Faber AndrΓ©s Vergara

Excellent post! The online tool that we use in the company where I work and has helped us with the commits is: commitlint.io/

Collapse
 
leew profile image
Wei Lee

Thanks for sharing! Would like to share this tool github.com/commitizen-tools/commit... which can help creating commit based on different rules (including convention commit)

Collapse
 
frankconnolly profile image
Frank Connolly

I tend to use feature branches so the scope part of the commit message is usually obvious based on that. Other than that I would steer towards this format as much as possible

Collapse
 
agesset profile image
Eag

Thanks for sharing ! I'll be sure to make my commit messages more precise.

Collapse
 
jeremysawesome profile image
Jeremiah Smith

I've been tossing a gitmoji at the beginning of commit messages these days. It offers similar categorization and makes it simple to see the intention of a commit at a glance.
gitmoji.dev/

Collapse
 
bunnyyum profile image
Tay

Thank you, this has been very helpful!