Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: I replaced "i.e." with "e.g." and added a bit pf punctuation. "e.g." =~ "for example"; "i.e." =~ "in other words".

...

Note

As an addendum, subjects should also be prefixed with a corresponding ticket number, ie.eg., "DDF-1234".

 


A good commit message looks like this: (from http://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines)

Code Block
DDF-1234 Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to
about 72 characters or so.  In some contexts, the first
line is treated as the subject of an email and the rest of
the text as the body.  The blank line separating the
summary from the body is critical (unless you omit the body
entirely); tools like rebase can get confused if you run
the two together.

Further paragraphs come after blank lines.

  - Bullet points are okay, too

  - Typically a hyphen or asterisk is used for the bullet,
    preceded by a single space, with blank lines in
    between, but conventions vary here

...


Why Does This Matter?

  • Points 1 and 2 are probably the most important ones. The convention of a short, meaningful title followed by a blank line is used throughout git, github, and many other tools. Following this convention helps produce more readable output from the various logging tools, makes things like annotate or blame more readable, and forces you to think critically and communicate clearly about the work you are doing in each commit.
  • Points 3, 4, and 5 will help you write good, consistent, readable titles. A title should answer the question of "When this commit is applied, it will...". A commit does something. It is an action performed on the codebase, and the title should reflect the imperative nature of commits.
  • Points 6 and 7 will help make the body of your commit message more readable, and ensure that it communicates the information other developers will need when they read it. The how is in the diff, your commit message needs to explain what and why.