Re: ChangeLog entries and hg

[John W. Eaton]

On 12-Apr-2011, 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.

I checked in a series of changes to stable and merges with default
that implement this change.

Now we no longer maintain ChangeLog files by hand.  You should follow
the style above for commit messages so they will generate reasonable
looking ChangeLog entries.  You can check the appearance of the
generated ChangeLog entry by running "make ChangeLog" in the top-level
build directory after you've committed a changeset.

I'll try to update the contributor guidelines in the next day or two,
but any suggestions or help with that would be welcome.

jwe