##############################
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`_.

.. _`Conventional Commits`: https://www.conventionalcommits.org/en/v1.0.0/#summary
.. _`it makes us better developers`: https://dev.to/maniflames/how-conventional-commits-improved-my-git-skills-1jfk
.. _`the changelog`: https://github.com/conventional-changelog/conventional-changelog

.. _`a tool in your CD pipeline`: https://github.com/mathieudutour/github-tag-action#bumping
.. _`the tool I found`: `a tool in your CD pipeline`_
.. _`a language-specific add-on/library`: https://github.com/pypa/setuptools_scm/#setuptools_scm
.. _`automate versioning and releasing based on VCS history`: https://github.com/rpatterson/python-main-wrapper/commit/39ad9377977b5544cc674dc837b4516b29e8ced7

.. _`Magit`: https://magit.vc/
.. _`my feature request`: https://github.com/magit/magit/issues/4027#issuecomment-816139428

.. meta::
   :description: Consider adopting a VCS commit message convention, `Conventional
                 Commits`_ has made me a better developer.
   :keywords: Conventional Commits, VCS, git, semver, Magit

.. post:: Apr 12, 2021
   :author: Ross Patterson
   :tags: Conventional Commits, VCS, git, semver, Magit