Re: ChangeLogs

[Thorsten Meyer]

John W. Eaton wrote:
> On  5-Jan-2009, Thomas Weber wrote:
> 
> | On Mon, Jan 05, 2009 at 11:23:23AM -0600, Jordi Gutiérrez Hermoso wrote:
> | > 2009/1/5 John W. Eaton <address@hidden>:
> | > > Or, we should simply decide to do away with ChangeLog files entirely.
> | > 
> | > Please don't... I like the Changelogs, since they're the only unbroken
> | > breadcrumb trail we have for Octave. If in a couple of years from now
> | > you decide that hg isn't doing the job anymore like CVS wasn't, then
> | > we'd lose the project's history when you switch VCS.
> | 
> | You should have more trust in current conversion tools. I'm pretty sure
> | you can switch between at least Mercurial and Git without loosing
> | anything.
> 
> Yes, and I would expect that would be true of any widely used VCS
> developed in the future as well.
> 
> | With distributed VCS, the importance of Changelogs has diminished. 
> 
> Yes, I agree.
> 
> | Generating changelogs with Mercurial isn't difficult, just try
> |     hg log --limit 2 --style=changelog
> | in Octave's directory. Adding something like this to 'make dist' hook
> | wouldn't be that much work.
> 
> OK.  If we are to do this, then we should
> 
>   Only generate ChangeLog entries after the point when we stop editing
>   them by hand.
> 
>   Agree on a format for the Mercurial log entries.  Future log entries
>   should contain more information than they do now.
> 
>   Instead of having multiple ChangeLog files (top, doc, src,
>   liboctave, libcruft, test, ...) There would only be one generated
>   ChangeLog file that we would put in the tar files we distribute.
> 
> I don't see how the generated ChangeLog entries can have precisely the
> format that we use now unless we edit it into the logs by hand anyway
> (I'm thinking of the
> 
>       * file (function): Description.
> 
> format -- it doesn't seem that Mercurial could do that for us).  But
> even without that, I'm OK with going this route once we decide on some
> guidelines for the way Mercurial log entries should be written.
> 
Actually, I like the two level documentation that the current ChangeLog
+ commit message gives:
 - top level description and purpose of the changeset in the commit message
 - individual changes in the ChangeLog

Can this somehow be preserved with an automated ChangeLog (without
having to type the file names again)?

Here is an example of the output of hg log -style ChangeLog for a larger
patch:
2008-12-27  Jaroslav Hajek  <address@hidden>

        * src/ChangeLog, src/oct-obj.cc, src/oct-obj.h, src/ov-base-diag.cc,
        src/ov-base-diag.h, src/ov-base-scalar.cc, src/ov-base.h, src/ov-
        bool-mat.cc, src/ov-bool-mat.h, src/ov-bool-sparse.cc, src/ov-bool-
        sparse.h, src/ov-bool.cc, src/ov-bool.h, src/ov-ch-mat.cc, src/ov-
        ch-mat.h, src/ov-colon.h, src/ov-complex.cc, src/ov-complex.h, src
        /ov-cx-mat.cc, src/ov-cx-mat.h, src/ov-cx-sparse.cc, src/ov-cx-
        sparse.h, src/ov-float.cc, src/ov-float.h, src/ov-flt-complex.cc,
        src/ov-flt-complex.h, src/ov-flt-cx-mat.cc, src/ov-flt-cx-mat.h, src
        /ov-flt-re-mat.cc, src/ov-flt-re-mat.h, src/ov-intx.h, src/ov-
        perm.cc, src/ov-perm.h, src/ov-range.h, src/ov-re-mat.cc, src/ov-re-
        mat.h, src/ov-re-sparse.cc, src/ov-re-sparse.h, src/ov-scalar.cc,
        src/ov-scalar.h, src/ov-str-mat.cc, src/ov-str-mat.h, src/ov.h:
        remove valid_as_scalar_index
        [f00578b495e9]

Now imagine this patch does 5 different kind of changes in 5 groups of
files to accomplish one major change. How should the ChangeLog look in
this case?
I think, it should still look like a list with 5 items for the 5 groups
of files. Is that possible with mercurial? For example, is it possible
to define a new style that will output (in ChangeLog format) only the
commit message  but not the list of files? Then we could simply write
into the commit message what we used to write into the ChangeLog files
preceded by another item, maybe like this:

purpose: fix a major bug
  * src/file1, src/file2: added this
  * scripts/file3, scripts/file4: removed that
  * doc/interpreter/file5: updated something else

regards

Thorsten