All of the examples given in the image going that heading I'd say are mediocre at best.
The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something.
A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much information on why you've changed it as you think would be useful.
#2313 Change expected value to a float field.
django-haystack stores decimal fields as strings internally.
This means that when we order by expected value small
values (e.g '9e-08') are sorted before larger values.Some commits even feature implementation details, and those I agree with you sometimes it makes sense to include them in the code. However most implementation details replace old ones, and this is transition should be explained in a commit since this is the perfect place for it.
Here is an random example from the linux kernel, which is guaranteed to do what I described: http://goo.gl/QdKNnJ
Ticket numbers are important context, but unless it is a one-off commit you can instead put that info in the merge commit (as if saying, all of these commits I'm merging were made as part of fixing Issue #17).
Some people like to use squash extensively for that reason, but then you don't have the same granularity when it comes to reverting individual bits of that commit without reverting the entire bugfix. (This assumes that every commit leaves the code in a working state with passing tests).
The alternative in your case (leaving it as-is, with an issue number) implies that the entire commit addresses that particular issue number, which may not be true. (It may be part of a series of commits for that issue)
Does anyone know of good open source project that uses Git messages extremely well that we could use as an example?
https://github.com/tomswartz07/linux-configs/commit/3684d3ad... is an example of one.
Git's commit log is probably the most detailed and informative log I've ever seen. And it's a bit fun to have a glance at Linus Torvald's old initial commits from 2005 :-)
(You might want to check the 'pu' branch rather than the 'master' branch. And there're lots of 'Merge branch...' commits that aren't super interesting.)
I have one coworker who continually fails to put the empty line between the first line and the body of the commit message. So many of our git logs are littered with 100+ character long messages.
The other commenters hit the nail on the head with the fomatting. Short, precise, and properly formatted.
- to explain HOW it works: comment in the code, so whoever comes to change the code later knows what should be touched and what should be left alone
- to explain WHY it was changed, use the bug tracker and just supply the #ID of bug/feature request in the comment
Having single-line comments makes it much easier to browse through history and find the thing you're looking for.
Unfortunately, the powers-that-be aren't too keen on enforcing something like that in our current projects.