
Writing good commit messages - kaeawc
https://github.com/erlang/otp/wiki/Writing-good-commit-messages
======
briandear
Tim Pope's article on commit messages is the gold standard.
[http://tbaggery.com/2008/04/19/a-note-about-git-commit-
messa...](http://tbaggery.com/2008/04/19/a-note-about-git-commit-
messages.html)

~~~
andreasklinger
Naive question: The present tense/imperative form is a standard i kind-of
adopted without ever questioning.

Why is better to write in that form?

~~~
cgdangelo
Just a guess, but I think it's because the message should indicate what the
commit itself does, not what _you_ did to write it. For example, by merging
this commit, the result is that I "Add X widget" to my code.

~~~
themckman
This is exactly how I describe this idea to people. I tell them to complete
the following sentence. "Applying this change set will...". I've recently
become less averse to verbs like fixes, updates adds, etc as I feel the
sentence "The change set..." is still pretty good. The key, obviously, being
you're describing the change set, not your actions.

------
Xcelerate
The imperative form makes no sense. You're not commanding that something
should be done -- you're telling what you have done. Unless there's a
compelling reason to violate the typical rules of grammar, I will stick with
past tense (or alternatively "fixes", "updates", etc.)

~~~
Karunamon
Came to say exactly this. If I see a commit message along the lines of :

    
    
        Fix bug foo
    

I'm going to assume that there is a bug that exists in this release that the
author intends to fix later. Kind of like a TODO, which is what it sounds
like.

~~~
activepeanut
There are much better tools to manage TODOs and bugs. Not to mention the
visibility of commit messages outside of the dev team.

------
Roboprog
Commit messages? Your developers write commit messages???

If I run a log on a file, and each commit has a sentence, I am a happy man.
But of course, I'm talking about work, not an open source project.

FYI: a more useful corporate standard is to reference a trouble ticket,
although having a descriptive sentence certainly helps (when you can get your
team to type anything at all, without a trigger to force it).

~~~
Roboprog
Which leads me to another pet peeve: javadoc comments.

Too many times I work on legacy code that where one third or less of the
contents have comments -- HUGE, flowery blocks, and the rest have NOTHING.

I'd much rather have a short sentence starting with a verb, and not "this
method will endeavor to attempt to proceed to ..." :-)

~~~
pjscott
Yes. Verbs! Good things. (No explicit verbs in this paragraph, though.)

In any case, the comment for a class or method (or whatever) should start with
a quick, concrete one-sentence description of what it is or does -- preferably
starting with a verb, as you said. If you want to elaborate later, great, but
everything needs the one-sentence summary. If I could tell inexperienced
programmers one thing, this would be a strong contender. (Other possibilities
include "Write your programs in discrete pieces that you can test in
isolation, as much as possible," and "Make it work _before_ you make it
fancy.")

------
jpalomaki
Sometimes it feels it might help if one would start by writing the the commit
message and then proceeding with the code edits.

Might be also good to see the summary line all the time - in the editor just
to keep myself focused.

------
highwind
I understand the justification for the DOs. But what's the purpose of that
single DON'T?

~~~
michaelmior
Given that the summary should be a single phrase, I find a period redundant
and when doing git log --pretty=oneline, it looks nicer without the period.

~~~
blinks
Doesn't seem like an amazing rationale; personally, I like periods -- they let
me know the writer finished their thought.

~~~
LoganCale
If it's the end of the message, one can assume the thought was completed
there.

------
bobz
Wow, just learned git add -p

That is fantastically useful.

*(Walks you through "hunks" (finer granularity than files) and asks if you want to stage them.)

~~~
zxoq
While useful, it's very dangerous in that it's serendipitous to make a commit
that breaks building the project, which in the future will break building the
project when checking out old commits, or introduce some subtle bug, which
breaks other tools like bisect.

Just a personal preference, but I strongly prefer being able to build (and
test) every commit in the entire history.

~~~
xyzzyb
So after you're done, go back through the commits and run your build tests.

[https://www.destroyallsoftware.com/screencasts/catalog/sourc...](https://www.destroyallsoftware.com/screencasts/catalog/source-
code-history-integrity)

------
azza-bazoo
I was hoping for less "here's how your commit message should be formatted",
and more "here's what your message should say". Though at least the blog it
links to[1] discusses the latter.

No guidance on how many changes should make up one good commit (versus
several)? No rules on referencing the issue tracker, or changes made by other
contributors? No suggestions for when to put useful information (like "always
do x when calling y()") in the commit or in a wiki or something?

[1] <http://who-t.blogspot.com.au/2009/12/on-commit-messages.html>

------
nraynaud
DON'T give an advice/order without explaining the rationale.

------
throwaway1979
I'm all for good commit messages. What I find frustrating is that it seems to
go against the "check-in often" mantra. I probably over check-in ... many
times a day. A feature might be 3-7 days or work. I try to make my commit
messages describe the specific change I made during that particular check in.
However, I feel no one would really care about commit messages like "Added
extra param to method Foo to remove global X.

~~~
msmith
One nice thing about git is that you can easily amend your commit history. If
you've done several related refactor commits in a row, then sometimes it makes
sense to squash them into one, using `git rebase -i` [1].

[1] [http://gitready.com/advanced/2009/02/10/squashing-commits-
wi...](http://gitready.com/advanced/2009/02/10/squashing-commits-with-
rebase.html)

------
tommorris
To see how _not_ to do it, I'd suggest Wikipedia's edit summaries. (I say that
in the spirit of love as a Wikipedia admin. :D)

<https://en.wikipedia.org/wiki/Wikipedia:ES>
<https://en.wikipedia.org/wiki/Wikipedia:ESL>

------
lancefisher
GitHub also recommends this style, and they format commit messages with that
in mind. <https://github.com/blog/926-shiny-new-commit-styles>

------
eperoumal
Good point here, I've run in too many gibberish commit messages. He could also
have mentionned "use good syntax and grammar".

