New Job - Old Problems

I started a new position recently. A good friend from a previous team invited me to come work with him, and soon after starting, I began to see why I'd come to mind, as his new team's issues mirrored a good many of the issues we'd faced together at NBC when we started there. The first one staring me in the face was one of the most obvious (at least as a coder): the git commit messages.

I'm going to be perfectly frank. You should NOT be using git commit -m "<insert message here>" when committing code. While yes, this is concise, it may not be as clear as you think, and more often than not, if you try to get informative with it, you're going to end up exceeding the max allotted space for that message. git commit -m is for hobbyists, for dabblers. It's the bare minimum information you should be including in your commit. As professionals, we should be providing more context, making things easier for those who come after us, and heck, why not, ourselves, while we're at it.

In order to provide a more informative git history, we should be using a .gitmessage template file, and favor using git commit over git commit -m '<message>' when writing commits.'

This format also has the added bonus of being able to automatically populate the subject and description of a pull-request on Github. (Provided you can manage to keep your branch history clean... but more on that in another post)

The below code snippet is the .gitmessage template I personally use, and can be pasted directly into a .gitmessage file, to be placed in your own home directory.

The headings (ISSUE, DESCRIPTION, STEPS TO TEST, REFERENCES, and CHANGELIST) should be uncommented prior to saving

# <type>:(<ref number>) <short summary> 
#   |           |               |
#   |           |               +-> Summary in present tense
#   |           +-> Refers to story/card/issue #
#   +-> Type: feat|bug|chore|fix|refactor|style|test
# Commit subject line should not exceed 50 characters.
# Remainder of gitmessage should wrap at 72 characters.
# Use github-flavored markdown for formatting and links
# (links should not be line-wrapped)
#
# __ISSUE:__
# _<type>_ - *<issue name>*
# \[[#<issue number](<issue url)\]
#
# __DESCRIPTION:__
# Why do we need this commit?
#
# ___STEPS TO TEST:__
# Step-by-step instructions for practical testing
#
# __REFERENCES:__ # (optional)
# Links to reference materials that may provide context
# ie:
# 1. [Better commit messages with a gitmessage template](https://thoughtbot.com/blog/better-commit-messages-with-a-gitmessage-template) - Matt Sumner
# 2. [5 useful tips for a better commit message](https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message) - Caleb Hearth
# 3. [A note about commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) - Tim Pope
# 4. [Linus' thoughts on commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) - Linus Torvalds
# 5. [Semantic commit messages](https://seesparkbox.com/foundry/semantic_commit_messages) - Jeremy Mack
# 6. [Github Flavored Markdown Spec](https://github.github.com/gfm/)
#
# __CHANGELIST:__
# Files Changed

The .gitmessage file should then be referenced under the 'commit' tag in your ~/.gitconfig file.

...
[commit]
  template = ~/.gitmessage
...

Usage Example:

fix: Update commit instructions (#1)

__ISSUE:__
_fix_ - *Update commit instructions*
\[[#1](http://fake.com/1)\]

__DESCRIPTION:__
The README.md file needed to be updated to correct outdated procedures

__STEPS TO TEST:__
1. Open Github
2. Navigate to the project
3. Read the README - text should be updated, spelled correctly,
   use proper grammar, and be clear and concise

__REFERENCES:__ # (optional)
1. [Link to a fake reference](http://fake.com)

__CHANGELIST:__
modified - README.md

I'm not just talking out of turn here, either... nor am I saying anything new; a lot of cool people feel your git messages should be more informative, and the work I brushed up on to write this article can be found in my list of references below. I invite you to read them yourself, and feel free to use my template, or experiment and come up with your own.

Until next time!

References:

1. Better commit messages with a gitmessage template - Matt Sumner
2. 5 useful tips for a better commit message - Caleb Hearth
3. A note about commit messages - Tim Pope
4. Linus' thoughts on commit messages - Linus Torvalds
5. Semantic commit messages - Jeremy Mack
6. Github Flavored Markdown Spec