Re: ChangeLog entries and hg

[Rik]

On 04/12/2011 11:25 AM, John W. Eaton wrote:
> On 12-Apr-2011, Rik wrote:
> 
> | On 04/12/2011 06:44 AM, John W. Eaton wrote:
> | > On 11-Apr-2011, Jordi Gutiérrez Hermoso wrote:
> | > 
> | > | The ChangeLog are gonna be particularly problematic with the new
> | > | workflow,
> | > 
> | > Yes, I realized that as soon as I tried a merge with a real change to
> | > Octave instead of just a simple change to a source file.
> | > 
> | > | If this isn't too much rabble-rousing, I think this is a good time to
> | > | adopt a new policy: hg commit messages should contain the details that
> | > | the ChangeLogs used to have, roughly in the same format; we keep the
> | > | ChangeLogs around for archival purposes, and we extract information
> | > | from the "hg log" command in order to generate future ChangeLogs for
> | > | tarball releases.
> | > 
> | > If we do this, then we need to be more careful about how we write
> | > ChangeLog entries.  Also, we should probably only have one ChangeLog
> | > file rather than one for each major directory tree in the sources
> | > since it won't be easy to automatically split out the hg commit
> | > messages and put some parts in one file and some in another.
> | > 
> | > Is there a tool for generating a ChangeLog file from an hg commit
> | > message?  The tool could assume that the log message is formatted like
> | > a ChangeLog entry.
> | 
> | Mercurial has "styles" which are templates for how the commit log should
> | look.  'hg log --style changelog' produces something that is reminiscent of
> | what we have now.  Documentation on using styles is here:
> | http://hgbook.red-bean.com/read/customizing-the-output-of-mercurial.html.
> | We could modify the changelog style or even post-process the Mercurial log
> | with something like Perl if we only need to do it once per release.
> 
> OK, the following might be enough of a style description:
> 
>   header = '{date|shortdate}  {author|person}  <{author|email}>\n\n'
>   changeset = '\t{desc|tabindent|strip}\n\n'
> 
> Then we would need to write commit log messages something like this:
> 
> maint: stop maintaining ChangeLog files by hand.
> * foo.tmpl: New file.
> * Makefile.am (dist): Depend on ChangeLog.
> (ChangeLog): New target.
> ...
> 
> There is no indenting in the log message, the first line is the
> summary, following lines are formatted much the same as current
> ChangeLog entries but should be wrapped at 72 columns to accommodate
> the leading tab that will be inserted by the hg log style when
> generating the ChangeLog file for the release.
> 
> We should be able to limit the generated ChangeLog file to only those
> commits that happen after we switch to the new way of working using
> the --prune option for hg log, and it should be simple to add a
> message at the end of the generated file that says where to find
> earlier entries.
> 
> I can take care of this change, but it may take a few days.  Until
> then, just keep using the same method of writing ChangeLog entries.
> 
> After the change, if we get changesets with ChangeLog entries, it
> should be easy enough to just generate a more verbose commit message
> from the ChangeLog entries in the changeset.
> 
> Is everyone OK with this change?
Yes, all for it.

For confirmation, is this about right?

changeset:   12596:5161d02c96b7
branch:      stable
tag:         tip
user:        Rik <address@hidden>
date:        Tue Apr 12 13:48:07 2011 -0700
files:       doc/interpreter/container.txi doc/interpreter/octave.texi
description:
doc: Add help text for dynamic naming "(var)" of structure fields.
* container.txi: Add help text.  Rename "Data Structures" to just "Structures"
* octave.texi: Rename "Data Structures" to just "Structures"

Or do you want the full directory path for the file, e.g.,
"doc/interpreter/container.txi" in the verbose comment?  Now that I write
this, I think the shortened form is fine because the full directory path is
available in the "files:" section from Mercurial and could always be
automagically copied down by a script of some sort.

--Rik