Re: Commit netiquette.

["Óscar Fuentes" <ofv@wanadoo.es>]

"Alfred M. Szmidt" <ams@gnu.org> writes:

>    The Committer used the full Changelog entry as the commit message, so on
>    interfaces that just shows the first line of the commit (like the
>    emacs-diffs mailing list or the output of `bzr log --short' or `qlog')
>    you see
>
>    2010-02-17  Mark A. Hershberger  <mah@everybody.org>
>
>    which is hardly indicative of the change.
>
> This seems more of a short comming in `bzr log --short' than in the
> way one writes commit messages.  A commit message is more than a
> single line.

This is like saying that "Subject" fields on e-mail messages are of
little use, that one always ought to look at the body of the message
before deciding if it is an interesting one.

> And the purpose of a change is always more suitable in the actual
> code as a comment.

Sure, but describing the purpose on the commit message is useful too,
mostly when the change is not circumscribed to a single point on one
file. Very handy for using with `annotate'.

On this respect I find changelog entries as a lame way of documenting
changes. Most of the time a changelog does not give more information
than what I quickly get combining `log' and `annotate', except when the
changelog entry documents the purpose of the change (not only *what*
changed) but this rarely happens. On projects that extensively use the
commit messages for documenting changes, using `log' and `annotate' is a
great learning tool when you are getting familiar with the code base.