What are commit messages for? I've always been writing them as an explanation of what I did, but I've recently gotten into a discussion about it with a colleague who writes commit messages explaining why he did. Which one is right, or is there another answer entirely?
NOTE: I have absolutely no idea if there is a "right" answer for this. As such, I've labeled it community wiki and will not accept an answer. Upvotes shall decide the winner :)
As a personal preference, I can tell what was done by looking at the differences in the files directly. The why is the thing I can't infer from just looking at the actual changes.
If the changes are significant or complicated, then I would include not only the why, but also a brief overview of the how.
I think both are useful. A quick description of what changed ("Adding length validation for AddUserForm") is easier than looking at a diff, especially if you're browsing multiple commits. Why the change was made, what bug it fixed, etc. is obviously a very good thing to have, too.
I use the commit message as an executive summary of what was changed.
Executive summary is a [...] short document that summarizes [...] in such a way that readers can rapidly become acquainted with a large body of material without having to read it all.
The why is documented somewhere else: an issue tracking system, requirements documentation, etc. I also include links from the commit message to the why, and vice versa.
Commit messages are what you make of them, but when there are hundreds of them for a particular file, or thousands for a project, you want to be able to scan through them looking for certain changes or the nature of the changes. In effect, they are like code comments, and they need to be as helpful as possible, yet concise and pithy. Maybe best to think of them as tweets - convey maximum meaning in a short space.
As somebody who's worked on large code bases spanning decades, and also smaller projects spanning a year or two, I've found nothing more infuriating when combing commit logs than messages like "oops" or "fixed bug". If you fixed a bug, tell us which one (a bug number, at the very least). It's all important for the inevitable forensics down the road.