Re: ChangeLog entries and hg

[John W. Eaton]

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?

jwe