Conventional Commits

I’m hoping to get a little feedback on this but a bit more of a brainstorm and let’s see where it goes.

I have been reading a lot of things about git in the last few weeks and trying to wrap my head around it more. I have stumbled on a number of things that could be labeled “best practices” and the other day came across this:

Conventional Commits

I think this is a great idea and I’m curious about other’s opinions. One thing I appreciate about this approach is that commits would give a lot more context and therefore be a better communication tool.

What I’m more curious about is how this can be best utilized for web development projects (either front or back end).

These commits use type and scope in the header. What kind of types and related scopes do you think would be useful in web-dev projects?

Or… what do you do or have you seen something similar?

I think Conventional Commits is a good distillation of existing convention, but I also think it’s a lot of structure that you should take as, well, convention. Not a rigid structure that You Must Always Obey Or Else.

Some good rules of thumb:

  • An individual commit should only fix or add ONE THING. How you define “one thing” will vary, but never bundle unrelated changes in a single commit.
  • The top line of a commit message should read as one sentence, as if you prefixed it with “This commit will …”. Any additional detail should, as the CC doc says, be “below the fold” so to speak, being separated by a blank line from the top line of the message.
  • Be consistent with your formats, but don’t be afraid to let them evolve as your needs change. Don’t get locked into a convention just because it’s convention.

One thing I would suggest is that if a fix references a particular bug number, put that number in the top line, not just the body below. For example:

fix(parser): close #1234 - correct off-by-one error in lexer

If your fix doesn’t actually close the issue, then just leave off ‘close’

In larger projects, you’ll find that every single change will be accompanied by a bug/issue ID, so this convention becomes a really powerful tool to track changes throughout your project.

As for scopes in web projects, you’re going to find new scopes as your project evolves. If you can’t think of a meaningful scope, just leave it out.

One additional thing I’ve noticed is that it’s become popular to prefix commit messages with various symbol emoji to indicate the type of change. This is cute, but if you use it, there should always be a textual description similar to how CC specifies it; it’s annoying to try to grep for an emoji in the commit log.

I really appreciate your reply! I havent been able to use git with other people much yet but I’m glad to hear from those with experience.

This is a good suggestion that you have for adding the issue number right in the top line along with close If it has been fixed. As I type I suppose having wip #324 (work in progress) would be good to use as well.

Thanks for taking your time Chuck. Cheers.

I have been moving more towards conventional commits on my own and work projects. I appreciate how they identify the type of work completed in the commit and also can provide more consistent tagging for git commits later.

An added benefit is for NPM packages. There are configurations to automatically adjust the version number of a package and generate the release notes when conventional commits are used. Several of my packages are published automatically when master changes including the generation of the changelog and version number. All of this reduces tedium of the release process through automation.