lib/ should have its own ChangeLog

lib/ should have its own ChangeLog

[Glenn Morris]

I suggest the lib/ (and m4?) directory should have a separate ChangeLog,
unless that makes syncing difficult for some reason.

Re: lib/ should have its own ChangeLog

[Paul Eggert]

On 02/09/11 14:39, Glenn Morris wrote:
> I suggest the lib/ (and m4?) directory should have a separate ChangeLog,
> unless that makes syncing difficult for some reason.

I don't think it makes syncing hard, from gnulib to
Emacs.  I can do that.

However, it will make writing ChangeLog entries a bit harder,
since I use vc-dwim
<http://www.gnu.org/software/vc-dwim/> and it doesn't
support checking in a single change with entries in
multiple ChangeLogs.  I can simply not use vc-dwim for
such changes, I suppose.  (Or modify vc-dwim to support
that as a new feature. :-)

I'll CC: this to bug-vc-dwim to give them a heads-up.

Re: [Bug-vc-dwim] Re: lib/ should have its own ChangeLog

[Ralf Wildenhues]

Hi Paul,

* Paul Eggert wrote on Thu, Feb 10, 2011 at 12:55:41AM CET:
> However, it will make writing ChangeLog entries a bit harder,
> since I use vc-dwim
> <http://www.gnu.org/software/vc-dwim/> and it doesn't
> support checking in a single change with entries in
> multiple ChangeLogs.

I'm not quite sure which part is lacking for you.
You can use
  vc-dwim ChangeLog lib/ChangeLog

or
  vc-dwim --commit ChangeLog lib/ChangeLog

after you've edited both of these files.

And you can use vc-chlog to generate stub ChangeLog entries for both of
the log files after you put this in your .vc-chlogrc file:

--changelog ChangeLog
--changelog lib/ChangeLog

Cheers,
Ralf

Re: [Bug-vc-dwim] Re: lib/ should have its own ChangeLog

[Paul Eggert]

On 02/09/2011 10:36 PM, Ralf Wildenhues wrote:
>   vc-dwim ChangeLog lib/ChangeLog

Thanks.  I could have sworn that I tried that and it failed,
but it just now worked for me.  Sorry about the noise.

Re: lib/ should have its own ChangeLog

[Stefan Monnier]

> I suggest the lib/ (and m4?) directory should have a separate ChangeLog,
> unless that makes syncing difficult for some reason.

I don't think that's needed.  It can use the top-level ChangeLog (or
even the src/ChangeLog).


        Stefan

Re: lib/ should have its own ChangeLog

[Paul Eggert]

On 02/09/2011 06:43 PM, Stefan Monnier wrote:
> I don't think that's needed.  It can use the top-level ChangeLog (or
> even the src/ChangeLog).

Hah!  I read that about 30 seconds after creating lib/ChangeLog
as revision 103207.  I reverted that, as revision 103208.

I prefer projects that use a single ChangeLog, as it's easier to
grok changes that affect multiple directories.  Would it be too
radical to propose a single ChangeLog for Emacs?

Re: lib/ should have its own ChangeLog

[Eli Zaretskii]

> Date: Wed, 09 Feb 2011 20:00:03 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: emacs-devel@gnu.org
> 
> On 02/09/2011 06:43 PM, Stefan Monnier wrote:
> > I don't think that's needed.  It can use the top-level ChangeLog (or
> > even the src/ChangeLog).
> 
> Hah!  I read that about 30 seconds after creating lib/ChangeLog
> as revision 103207.  I reverted that, as revision 103208.

May I suggest a slower reaction times?  (To changes in gnulib as
well.)  I think it will improve our life qualities.

Re: lib/ should have its own ChangeLog

[Glenn Morris]

Stefan Monnier wrote:

>> I suggest the lib/ (and m4?) directory should have a separate ChangeLog,
>> unless that makes syncing difficult for some reason.
>
> I don't think that's needed.  It can use the top-level ChangeLog (or
> even the src/ChangeLog).

Every other top-level subdir with > 1 file has its own ChangeLog.

The other part of my motivation was, I'm not sure the very detailed
ChangeLog entries imported from gnulib (eg 2011-01-30, which is 50% of
the length of the whole nextstep/ChangeLog) are of much relevance to
Emacs; so I think it would be better to keep them more separate, if they
are needed at all (as opposed to just, eg, "update from master").

Re: lib/ should have its own ChangeLog

[Paul Eggert]

On 02/09/2011 08:52 PM, Glenn Morris wrote:
> I'm not sure the very detailed
> ChangeLog entries imported from gnulib (eg 2011-01-30, which is 50% of
> the length of the whole nextstep/ChangeLog) are of much relevance to
> Emacs

It would save me time to use shorter ChangeLog entries, and I could
easily be persuaded to replace long entries like that with "update
from master", regardless of which directory we decide to put the
ChangeLogs in.

Re: lib/ should have its own ChangeLog

[Eli Zaretskii]

> Date: Wed, 09 Feb 2011 22:24:17 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> On 02/09/2011 08:52 PM, Glenn Morris wrote:
> > I'm not sure the very detailed
> > ChangeLog entries imported from gnulib (eg 2011-01-30, which is 50% of
> > the length of the whole nextstep/ChangeLog) are of much relevance to
> > Emacs
> 
> It would save me time to use shorter ChangeLog entries, and I could
> easily be persuaded to replace long entries like that with "update
> from master", regardless of which directory we decide to put the
> ChangeLogs in.

In general, since we are using a changeset-oriented VCS, the detailed
descriptions of the changeset are supposed to be part of the commit
log messages.  ChangeLog entries can just state what was changed;
there should be no need to repeat in the ChangeLog what is described
in the commit log message.

Re: lib/ should have its own ChangeLog

[Paul Eggert]

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:

2011-02-10  Ken Manheimer  <ken.manheimer@gmail.com>

        * allout.el: Synopsis: Change allout user configuration so
	auto-activation is controlled solely by customization
        `allout-auto-activation'.

        (allout-auto-activation-helper) (allout-setup): New autoloads
        implement new custom set procedure for allout-auto-activation.
        Also, explicitly invoke
	(allout-setup) after allout-auto-activation is custom-defined, to
        effect the settings in emacs sessions besides the few where
	allout-auto-activation customization is donea.
        (allout-auto-activation): Use allout-auto-activation-helper to
        :set.  Revise the docstring.
        (allout-init): Reduce functionality to just customizing
	allout-auto-activation, and mark obsolete.
        (allout-mode): Respect string values for allout-auto-activation.
	Run allout-after-copy-or-kill-hook without any args.
        (allout-mode) (allout-layout) (allout-default-layout)
	(outlineify-sticky): Adjust docstring for new scheme.
        (allout-after-copy-or-kill-hook): No arguments - hook implementers
        should concentrate on the kill ring.

Re: lib/ should have its own ChangeLog

[Eli Zaretskii]

> Date: Wed, 09 Feb 2011 23:36:53 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: rgm@gnu.org, monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> 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  <ken.manheimer@gmail.com>

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  <eliz@gnu.org>

	  * 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 <eliz@gnu.org>
    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  <eggert@cs.ucla.edu>

  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.

Re: lib/ should have its own ChangeLog

[Stefan Monnier]

>> 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.

Actually, the ChangeLog should contain the exact same text as the commit
message, so we can eventually auto-generate the ChangeLog(s).


        Stefan

Re: lib/ should have its own ChangeLog

[Paul Eggert]

On 02/10/2011 10:09 AM, Stefan Monnier wrote:
> Actually, the ChangeLog should contain the exact same text as the commit
> message, so we can eventually auto-generate the ChangeLog(s).

That sounds like a good idea, and I'm used to it in
other projects, such as coreutils.  How about if
we do that with Emacs too?  It is confusing and
wastes our time to keep two sets of logs when
one would do.

Re: lib/ should have its own ChangeLog

[Stefan Monnier]

> That sounds like a good idea, and I'm used to it in
> other projects, such as coreutils.  How about if
> we do that with Emacs too?

I'd love to.  There are some obstacles, tho:
- make "C-x 4 a" work for such uses.
- figure out how to generate good quality ChangeLog files (we should
  probably keep the current ChangeLogs and only auto-generate entries
  for the new commits, since some of the past commit messages aren't as
  good as the ChangeLog).
- figure out how to handle errors in commit messages: apparently Bzr is
  unlikely to support editing its commit logs much before hell freezes
  over, so we'll have to hack something on top of Bzr on our side.

> It is confusing and wastes our time to keep two sets of logs when one
> would do.

log-edit lets you drag the ChangeLog entry into the *VC-Log* buffer, so
it's usually not too painful, but yes, it's inconvenient, especially
when merging branches.


        Stefan

Re: lib/ should have its own ChangeLog

[Glenn Morris]

Stefan Monnier wrote:

> log-edit lets you drag the ChangeLog entry into the *VC-Log* buffer, so
> it's usually not too painful, but yes, it's inconvenient, especially
> when merging branches.

Try Bzr's changelog_merge plugin, now documented in admin/notes/bzr.