[Style] Git Commit Messages

[James Socol]

Welcome to another pedantic, style/standardization email. This time, we're talking about git commit messages.

I hinted at this in the original process changes email, but I want to get everyone to use the following standard for commit messages. To this end, I won't r+ any patches that deviate from it. (Though they may be "r+(if you fix the commit message)").

[fix bug 123456] This line is 50 chars or less.

More detail goes here, if necessary. You can add multiple paragraphs,
or
- lists
- if
- you
- need

Whatever it takes. Please wrap this to 72 characters.

A couple of particular requests:

• Note the casing. "fix bug" is lowercase, the rest of the first line is capitalized like a sentence...
• ...because it's a sentence. Active voice, present tense is best.
• The second line is blank.
  
• Use complete, capitalized sentences. This lines up with PEPs about documentation and will help ESL contributors by keeping our language a little more formal.
  

There are a bunch of reasons for this, mostly stemming from the fact that all sorts of tools assume the first line will contain this density of information, and will only display the first line ("short-log" format) most of the time:

• Putting "[fix bug 123456]" in a commit message makes GitHub automatically resolve the bug when it lands on master.
• Putting it on the first line makes Jenkins linkify "bug 123456", since it only uses the first line (i.e. the short-log line) in many/most of its interesting views.
  
• Putting it on the first line makes it easy to see the bug # in any short-log format, including GitHub comparison views (for example, looking at the patches applied to 'next' since the last tag).
• It'll even cause some nice IRC clients to linkify "bug 123456" when bots (like baconmatt) dump short-log commit messages.
  
• GitHub (and some other short-log formats) truncates the first line to 50 characters. Being succinct is good.
• By always putting the bug # in the same place, we humans also know where to look for it.
  

Unfortunately, the only way to really enforce consistency with these things is to be pedantic and forceful, e.g. to deny review, so that's what I'll do.

Fortunately, it'll be better for everyone and shouldn't be too hard to get used to.