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.
I prefer to keep such comments in the code, not in the commit message. It is highly unlikely that anyone coming to do some changes to that part of the code would go and read a year-old commit message that he isn't even aware exists.
There is a difference tough, a very subtle one. A commit body should describe the rationale of the change, i.e. any decisions that had to be made or trade-offs in light of developer discussions and so on. Basically a description of the issue being solved. These things are rarely needed in the code itself, as the code will most likely feature new things and the old things are history.
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
The example I gave (happened to be what I was working on) would be quite pointless as a comment. Since the code could easily have been written using the float datatype.
Try using git blame. It tells you what change caused a line to happen. I often use it to find out exactly what issue caused a seemingly crazy bit of code to happen. As the code goes away, so does the commit message - not necessarily so with a comment.
While that's true; `git pickaxe` will also do what you describe.
The added bonus is that one could use pickaxe to follow a specific line's changes way farther back than a normal comment.
You can run git blame to get the information pertaining to that particular line of code. That's a really good way to document what a particular piece of code is doing and why at the time it was written.
You're right -- the diff answers the what, so being able to answer the why concisely is what makes a good commit message.
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).
I guess in that scenario my preference would be to amend the cherry-picked commit's message to include why it was cherry-picked.
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)
This creates a lot of noise on GitHub though. I prefer to put the issue number in the branch name and in the PR description. But for one-off commits, it goes in the commit message.
Yeah, I prefer the issue number in each commit as it makes the commit log more readable to me. But do a decent job of everything else and that is a very small nit-pick.
I agree it useful, but it's more useful overtime than anything, on the short term, issue numbers are not really useful. You are right, those examples were not our best ones ;)
I think the point was mostly that 'lol' or 'meh' is a completely useless comment. It's true that there's a lot of room for improvements in the given example. Still, they do provide some context to people who actually understand the application they are working on.
Does anyone know of good open source project that uses Git messages extremely well that we could use as an example?
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.)
Yes, totally! We picked some examples quickly just to demonstrate that people can do better "lol", "fix" or "meh". There is still room for improvements and we have better ones, too.
One of my biggest pet peeves is poorly formatted commit messages.
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.
We had an interesting policy in the company where I worked before and I use it for my own projects: only one line is ever allowed - explaining WHAT was changed.
- 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.
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.