GitHub Commit Message Standardization

Posted on by under Software Engineering, Work

heisencat.pngA while ago at work, I found myself looking at a pull request and I realized that my commit messages were weak and did not properly convey the intent of the change. This was a weakness, writing meaningful commit messages, I often found myself needing to improve upon. At work, I wrote an email about this back in September.

Just as code should be self documenting, outlining a best practices for commit messages will do the same for pull requests.

I Googled a bit and there is a lot of opinion (and official git suggestions) and tips on how best to go about this. It’s hard to rationalize enforcement because it means we may reject solid code with less than ideal messages. In the same sense though, I would reject functional code that has poorly named variables or functions.

GitHub Commit Message References

The official suggestion can be found documented in the git-scm website:
http://git-scm.com/book/ch5-2.html
(I didn’t get a chance to read this one entirely yet, just skimmed it)

The TL;DR version is summarized in the following repository:
https://github.com/erlang/otp/wiki/Writing-good-commit-messages

The GitHub repository above references the git-scm book and a solid blog post about commit messages:
http://who-t.blogspot.com/2009/12/on-commit-messages.html

“Consider this is a hint for proprietary software companies too – not having decent SCM discipline costs money!”

Here is one more quick blog post on commit messages with “The seven rules of a great git commit message”:
http://chris.beams.io/posts/git-commit/

Standards Proposal

Why:

  • To speed up the reviewing process.
  • To help the future maintainers find out why a particular change was made
  • To help us write a good release note.

How:

  • A commit should contain exactly one logical change
    • If it’s not possible to describe the high level change in a few words, it is most likely too complex for a single commit
  • Follow industry standard git format messages
    • A short one-line summary of the change (less than 50 characters)
      • Make it count
      • Capitalize the subject line
      • Do not end the subject line with a period
      • Use the imperative mood in the subject line
    • After that one-line summary, an empty line, then multiple paragraphs explaining the patch in detail (if needed)
      • Don’t describe the code, describe the intent and the approach
        • E.g.: why vs how
      • Wap the body at 72 characters
  • Commit files in logical groups
    • Avoid per-file commits when not necessary
  • No lazy commit messages
    • Personal example in most recent, “Code Cleanup”

 

Format:

[Ticket # : ]Imperative mood summary of change  | < 50 characters
[ Empty Line]
[Paragraph(s) of relevant patch details]        | < 72 characters

Leave a comment