Re: Referring to revisions in the git future.

[Eric S. Raymond]

Stefan Monnier <address@hidden>:
> >> About summary lines, a reminder: Please don't write the traditional
> >> GNUish run-on change comment with a semi-infinite number of bulleted
> >> items in it any more.
> >     That's your opinion, but the convention we still use here (and don't
> >     just recommend but *request* people to follow) is the GNU ChangeLog
> >     format.
> > You can have both.  In other GNU projects using git (gdb, binutils) we
> > include a summary line for the benefit of `git log --oneline', followed
> > by an extended description in a separated paragraph(s) and finally the
> > ChangeLog entries.
> 
> We do like to have a summary line as well, indeed (that's part of the
> reason why 24.4 has now "Summary:" in the default content of the
> *VC-Log* buffer where you write your commit message).  But Eric was
> recommending not to include the full ChangeLog thingy.

Eh?

No. As I just said to Jan Djarv, including the full ChangeLog thingy 
is fine *as long as there's a proper summary line in front of it*
In other words, we need to move from this (marking start and 
end of comment with '-----'):

---------------------------------------------------------
* foo.c: Add a mutex around struct grobble so queue updates can be
thread-safe
* bar.c, baz.c: Assert mutex to avoid data scrambleage.
---------------------------------------------------------

to this:

---------------------------------------------------------
Properly mutex-lock the grobble structure.

* foo.c: Add a mutex around struct grobble so queue updates can be
thread-safe
* bar.c, baz.c: Assert mutex to avoid data scrambleage.
---------------------------------------------------------

Now, in the longer term, I think changeset comment logs will and
should replace ChangeLog files entirely, but that's a different
conversation.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>