Endorsing Conventional Commits¶
Consider adopting a VCS commit message convention, Conventional Commits has made me a better developer.
Over the years when starting a new project, I usually found myself staring at the cursor in my editor when it prompts me to write the commit message for my first commit and thinking “Is there a convention for this?”. Sometimes the project would have it’s own convention, which was always refreshing. That has been, unfortunately, rare and each such project usually ended up being the only one that uses that particular convention. In the last few years, I’ve been using Conventional Commits here and there. When I went looking for a tool to automate versioning and releasing based on VCS history, the tool I found uses Conventional Commits which pushed me over the edge to endorsing and advocating for it.
The primary reason I reach for a commit message convention is how much easier it makes
visually scanning and make sense of VCS logs as a human. It makes a world of
difference. Trying to remember that cool application logic you wrote because you need
something similar again now but all your $ git log -G... efforts have come to
naught? Browsing the log narrowed to $ git log --grep'^feat' will most often get
you there a lot faster when compared to iterating through the whole log. For everything
from $ git blame ... to CI failure messages to picking out-of-place commits in a PR,
having this extra metadata as well as declaration of intent and scope in every commit
has a thousand little incremental benefits that really add up for the humans that have
to interpret commit messages.
The second most important reason for a convention, IMO, is it makes us better developers. It certainly has made me a better developer. When we add more structure to our commit messages and there is meaning attached to that structure, then writing commits forces us to think about those aspects of development at the time we are committing changes. When my commit message convention includes a piece of structure that declares how this change relates to releasing, versioning, and the changelog, then I am forced to think about those things before committing. If the changes I was intending to include in this commit include some backwards incompatible refactoring and a new feature, the convention will force me to realize I need to refactor this commit into two separate commits. It may also help me to think of a way to rework the changes to be backwards compatible.
Finally, using a commit message convention allows us to use tools to automate
versioning, the changelog, and releasing. Use a tool in your CD pipeline, so that
when you merge develop into master and $ git push, the CD pipeline will
create a new version tag using the convention to determine whether the next version
should be a patch version for bug fixes, a minor version for backwards compatible
features, or a major version for backwards incompatible changes. Next, the CD pipeline
kicks off the language-specific process to build release artifacts and a
language-specific add-on/library uses that new version tag to determine the version to
use in the release artifacts. Finally, the CD pipeline will upload those release
artifacts to the appropriate registry/index.
IOW, merge, push, and walk away. Release discipline becomes a part of code review, e.g.: “The commit message says this is a backwards compatible feature but this change is not backward compatible. Please rework this change to be backward compatible or, if not possible, change the type in the commit message.” No manual version bump or changelog update steps. No duplicated version information. There are far fewer mind numbing chores for the release manager leading to less burn out in that role and more frequent releases.
Since I started using Conventional Commits, I’ve just formatted my commit messages thusly and when working with a team I’ve only shared my enthusiasm when a teammate asked. Having done so for a while now, I think I’m ready to start taking a more active tack and proselytizing to my teammates going forward; for the use of a convention in general, and Conventional Commits in particular. I can’t imagine going back, certainly not back to commit messages without some convention. I’m pretty thoroughly sold on the benefits, even when not using the CD tools that take advantage, and I honestly can’t think of a downside. So give it a shot, embrace the discipline, and see if you feel the same.
P.S.: If you agree and you’re a Magit user, please +1 my feature request.
Comments
comments powered by Disqus