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.