Re: lib/ should have its own ChangeLog

[Eli Zaretskii]

> Date: Wed, 09 Feb 2011 23:36:53 -0800
> From: Paul Eggert <address@hidden>
> CC: address@hidden, address@hidden, address@hidden
> 
> On 02/09/2011 11:04 PM, Eli Zaretskii wrote:
> > detailed
> > descriptions of the changeset are supposed to be part of the commit
> > log messages.  ChangeLog entries can just state what was changed;
> 
> This seems to imply that ChangeLog entries are short and commit
> logs are long.  But in practice the reverse is common, with the detailed
> description is in the ChangeLog, and the commit log being a brief
> summary.  I'm used to this tradition and don't see why it should
> (ahem) change.
> 
> For example, for the most recent entry in lisp/ChangeLog the
> commit record is short:
> 
>  * allout.el: Synopsis: Change allout user configuration so auto-activation
>   is controlled solely by customization `allout-auto-activation'.
> 
> whereas the ChangeLog entry is long:

I didn't mean "short" vs "long", I meant "explanations of the
rationale" vs "just the log of changes".  Sorry for being unclear.

> 2011-02-10  Ken Manheimer  <address@hidden>

This is not a good example of what I meant, because it mixes the
change logs and explanations in both the ChangeLog file and the commit
message.  What I meant is this:

  2011-02-04  Eli Zaretskii  <address@hidden>

          * makefile.w32-in (LISP_H, PROCESS_H): New variables.
          Replace all uses of lisp.h with $(LISP_H), and all uses of
          process.h with $(PROCESS_H).
          ($(BLD)/editfns.$(O)): Depend on ../lib/strftime.h.
          ($(BLD)/print.$(O)): Depend on ../lib/ftoastr.h and ../lib/intprops.h.

This describes specifically what was changed and how, but not why.

    revno: 103116
    committer: Eli Zaretskii <address@hidden>
    branch nick: trunk
    timestamp: Fri 2011-02-04 17:32:34 +0200
    message:
      Update dependencies in src/makefile.w32-in.

The "message" part says what was the rationale for the changes.

2011-02-07  Paul Eggert  <address@hidden>

  conform to C89 pointer rules

  * dired.c (scmp, file_name_completion):
  Change types between char * and unsigned char *, to satisfy C89
  rules about pointer type compatibility.

This does both.  I would have only this in the ChangeLog:

  * dired.c (scmp, file_name_completion):
  Change types between char * and unsigned char *.

And in the commit log message say this:

  Change types between char * and unsigned char *, to satisfy C89
  rules about pointer type compatibility.

Anyway, this is a question of style, and I'm not sure others will
agree.  But this is my opinion, FWIW.  My rationale for doing this is
that the commit logs are the main instrument of forensics, so keeping
the "why's" there gives onbe less place to look into.