How to make devs write better commit messages

How to make devs write better commit messages

[Joseph Huttner]

So I know that there is a somewhat standard format of commit messages
in Git, which Linus outlines here:

https://github.com/torvalds/subsurface/blob/master/README#L164

Trouble is, when most people go to commit, the file that the editor
opens has no reminder of how to write a proper commit message.  Often
I find myself having to go back through the commit log, or consulting
the above link.

I propose two things:

1.  An optional flag in the Git config that, if set, shows the format
of a typical commit message in your commit message template.

2.  The ability to modify this commit message template.  Many teams
use automated tools to read commit messages and then do automated
tasks based on that data, like comment an RT ticket.  Thus, developers
need to be reminded of these team-specific settings as well.

What are your thoughts?

The bottom line is that good commit messages are really important, so
we should make it as easy as possible for developers to go ahead and
write a perfect commit message every time they commit code.


E.g.


# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
# modified:   application/views/layouts/layout.phtml
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
# public/js/databases/
#
# How to properly format your commit message:
#
# 	Header line: explaining the commit in one line
#
#	Body of commit message is a few lines of text, explaining things
#	in more detail, possibly giving some background about the issue
#	being fixed, etc etc.
#
#	The body of the commit message can be several paragraphs, and
#	please do proper word-wrap and keep columns shorter than about
#	74 characters or so. That way "git log" will show things
#	nicely even when it's indented.
#
#	RT: 123, 456 [a comma-separated list of RT tickets this commit refers to]
#

Re: How to make devs write better commit messages

[Michael Schubert]

On 12/06/2011 11:55 PM, Joseph Huttner wrote:
> So I know that there is a somewhat standard format of commit messages
> in Git, which Linus outlines here:
> 
> https://github.com/torvalds/subsurface/blob/master/README#L164
> 
> Trouble is, when most people go to commit, the file that the editor
> opens has no reminder of how to write a proper commit message.  Often
> I find myself having to go back through the commit log, or consulting
> the above link.
> 
> I propose two things:
> 
> 1.  An optional flag in the Git config that, if set, shows the format
> of a typical commit message in your commit message template.
> 
> 2.  The ability to modify this commit message template.  Many teams
> use automated tools to read commit messages and then do automated
> tasks based on that data, like comment an RT ticket.  Thus, developers
> need to be reminded of these team-specific settings as well.
> 
> What are your thoughts?

If it's no social issue but just due to lack of a reminder you
could provide a template for commit.template. Either way: you
still would have to force people to set it.?

Re: How to make devs write better commit messages

[Junio C Hamano]

Michael Schubert <mschub@elegosoft.com> writes:

>> What are your thoughts?
>
> If it's no social issue but just due to lack of a reminder you
> could provide a template for commit.template. Either way: you
> still would have to force people to set it.?

While that would be a good first step, I think people will learn best when
they feel by their skin how good log messages help them in the long run.

Pick a recent bugfix in your project, analyze why the code was broken by
the bug in the first place, and view the log message of the commit that
introduced the code that was broken by the buggy commit. You will often
notice that the original commit did not explain why the code needs to be
that way sufficiently, risking later breakage, and the buggy commit that
broke the code did not justify the change any more than "This happens to
make something work for me in a particular narrow case".

And then look at the log message of the bugfix. Does it explain why the
broken change was bad, and the fixed code _has to be_ that way?

Do this for a handful of examples, and you will start noticing patterns,
and what makes good messages that become useful in the longer term. Have
your people learn from good ones _as well as_ the bad ones.

Have fun.

Re: How to make devs write better commit messages

[Hilco Wijbenga]

On 6 December 2011 14:55, Joseph Huttner <huttnified@gmail.com> wrote:
> So I know that there is a somewhat standard format of commit messages
> in Git, which Linus outlines here:
>
> https://github.com/torvalds/subsurface/blob/master/README#L164
>
> Trouble is, when most people go to commit, the file that the editor
> opens has no reminder of how to write a proper commit message.  Often
> I find myself having to go back through the commit log, or consulting
> the above link.
>
> I propose two things:
>
> 1.  An optional flag in the Git config that, if set, shows the format
> of a typical commit message in your commit message template.
>
> 2.  The ability to modify this commit message template.  Many teams
> use automated tools to read commit messages and then do automated
> tasks based on that data, like comment an RT ticket.  Thus, developers
> need to be reminded of these team-specific settings as well.
>
> What are your thoughts?

Great idea! These templates would be stored in the Git repo, I assume?
Btw, there is 'commit.template' which you can use locally.

 I was wondering if it might be possible to somehow add project config
defaults to one's Git repo. It would be great to have something like
'commit.template' point to a file in the Git repo by default.
Currently, it doesn't seem possible to have a config parameter "point
to" a file or directory in the Git repo. Nor do I know of a way to
have the Git repo set a config parameter to a default value. Or is
this possible after all?

Re: How to make devs write better commit messages

[Thomas Koch]

Joseph Huttner:
> The bottom line is that good commit messages are really important, so
> we should make it as easy as possible for developers to go ahead and
> write a perfect commit message every time they commit code.

I recently started to work with the code review system Gerrit[1]. First I did 
not pay attention to it, but later I was amazed that the commit message can 
(and should) be reviewed just like the code changes.

So if you're using a code review prozess (you should!) then also include the 
commit message in the review.

[1] http://en.wikipedia.org/wiki/Gerrit_%28software%29

Thomas Koch, http://www.koch.ro