Commit messages

[lucashorward]

I propose we establish some guidelines about the git commits, so that we maintain readability of the history and are able to review changes more efficiently.

Specifically, I propose the following guidelines, based on an article from Chris Beams (Read it here):

1. Use the imperative mood in the subject line
2. Keep the subject to 50 characters or less, more detailed explanations belong in the body
3. Use the body to explain what and why instead of how

Chris makes 4 other points, which can be useful, but I would not consider them mandatory (so we would not deny a commit if the body line length is more than 72, for example)

I would like to see these 3 rules enforced, and require commits to be renamed if they do not meet these standards, or if the reviewer in question cannot understand what has been changed from the commit subject line.

[Baudin999]

I've been thinking about this and I have the following challenges:

Let's look at the premise of the article:

A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.

Assume that this is right. A maintainer has few tools more powerful that his project's log. What are you maintaining? The quality of the code? The correctness of the functionality?

I would venture that none of these things can be derived from the commits or the messages. A beautiful message can hide a horrible implementation.

I agree with:

1. You need to "glean" what has been changed from the message. Stuff like "ASDAASDasdasd" should not be committed. This is what the reviewer of the pull request is form

2. Commit messages (your log) should never, ever, ever, ever, be changed. This is your audit trail, people know these messages and changing them distorts the reality.

3. Use commits to push the changes to a Source Control Management System use your tests to describe what you've created. Code coverage, tests success/failure and code structure should tell this story. I want people to look at the code, not the commit messages.

Conclusion, I think it's important to use the commit messages to leave a good trail but they are not that important that I want to use rules. Most of the enforcing I want the reviewer of the pull request to do. Leaving this up to only a few people should solve the problem.