Re: ChangeLogs in commit messages

[Joel Brobecker <brobecker at adacore dot com>]

>   1. With paths and with the date-and-author header:
> 
>     gdb/
>     2014-07-30  Gary Benson  <gbenson@redhat.com>
> 
>             * btrace.c: Include defs.h.
>             * common/ptid.c: Include defs.h or server.h as appropriate.
>             * nat/mips-linux-watch.c: Likewise.
> 
>   2. With date-and-author headers but no paths:
> 
>     2014-08-04  Tom Tromey  <tromey@redhat.com>
>       
>             * gdb.base/sss-bp-on-user-bp-2.exp: Match "to_resume", not
>             "target_resume".
> 
>   3. With paths but no date-and-author headers:
> 
>     gdb/ChangeLog:
>       
>             * amd64-windows-tdep.c (amd64_windows_frame_decode_insns):
>               Add debug trace.
> 
>   4. With no preamble at all:
> 
>             * chew.c (print_stack_level, main): Cast result of pointer
>             difference to match format string.
> 
> What are people's preferences here?  My preference is #1, but I could
> live with #3.  If we come to some kind of concensus on this I'll
> update the wiki to reflect this.

#3, since date and author are often redundant with the commit's
author. And even if not in the same, it's in the ChangeLog entry
that should be checked in as part of the commit. Also, I feel
like having those in the CL is an extra source of potential
issue (eg: if forgot to update the date), and revision logs
cannot be fixed once the commit has been pushed, whereas dates
in ChangeLog entries can.

But I can also live with #1. Not super keen on #2 and #4 in the sense
that it seems important to me to say which ChangeLogs are being
updated, since filenames are relative to those.

I do think we can be a little flexible without much downside,
and therefore have a set of accepted practices.

-- 
Joel