Issue #s in commit summary lines

A topic recently came up on my team about commit messages. It's common for teams to strugle with commit messages, especially young teams with poorly defined standards (like the one I'm on), and we are no exception. I'll admit, I get lazy or forget to write well crafted commit messages. It's not unheard of for one of my commits to only say "Fixing tests" or something equally useless. But, in general, I try to write well formatted and descriptive commit messages.

A few days ago, one of the several lead engineers decided to mandate that the ID of the issue a commit was for be included on the summary line for every commit. One thing I routinely struggle with is cramming a decent summary into the 70~ char softlimit for git commit summaries. Why would I want to give up some of my valuable characters for something that is almost (at a glance) useless! The reasoning was it would make it easier to track when doing large merges (we're using a variation of Gitflow) and to help with an overall understanding of what's in a codebase. I'm generally inclined to agree with the goal, but the status line is a terrible place to put what is essentially a foreign key to an external issue (in our case, JIRA). Now to be clear, I'm absolutely in favor of referencing the issue ID in the commit message, just not in the summary line.

There are several reasons why referencing an issue tracker ID in the summary. One of the primary ones, in my opinion, is it clutters the summary. To someone looking at the code out of context, or even in context but couldn't be bothered to remember the actual issue related to task #2357, the ID has no meaning. It tells the reader absolutely nothing about what the change is doing or why it's being made. Further, issue trackers can change or get shut down. It's life is not directly tied to the life of the code. Years down the road, some poor soul could be sifting through commit history littered with references to a JIRA instance that has long since been shut down. Ouch.

I personally like to write my commits using a specific format:

commit example

Brief explanation of the what and why of the changes contained in the commit
Resolves: JIRA-01

There is, of course, no "right" way to write a commit message. I, in general, try to follow the guidelines described in The Art of the Commit. The format of the commit message isn't nearly as important as the what.