Re: policy for pushing changesets

[John W. Eaton]

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.

One example to look at is the coreutils project's git log messages and
the ChangeLog files that are generated from them.  You can browse the
git archive here:

  http://git.savannah.gnu.org/cgit/coreutils.git

The log messages tend to contain a lot more information about the
rationale for a change than is normal for a ChangeLog entry.  I don't
have a problem with that, though it is counter to previous policy of
saying what changed in the ChangeLog file and explaining why in
comments in thecode, with the reasoning being that people will later
be looking in the code, not some random spot in the VCS history (which
they might not even have access to).  So I still think it is best to
put the rationale for a change in the sources, not in the commit log. 

What I definitely want to avoid is a series of commit
messages/ChangeLog entries that all say "fixed bug".  To be useful,
the entries need to say more than that.

As an example, the coreutils guidelines for commit log messages seem
reasonable and are

  Commit log requirements
  =======================
  Your commit log should always start with a one-line summary, the second
  line should be blank, and the remaining lines are usually ChangeLog-style
  entries for all affected files.  However, it's fine -- even recommended --
  to write a few lines of prose describing the change, when the summary
  and ChangeLog entries don't give enough of the big picture.  Omit the
  leading TABs that you're used to seeing in a "real" ChangeLog file, but
  keep the maximum line length at 72 or smaller, so that the generated
  ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
  As for the ChangeLog-style content, please follow these guidelines:

    http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html

  Try to make the summary line fit one of the following forms:

    program_name: change-description
    prog1, prog2: change-description
    doc: change-description
    tests: change-description
    build: change-description
    maint: change-description

Here, program_name or prog1, prog2 would be replaced by actual
program names like cp or mv for the coreutils.  The others are
literal.  We might use function_name instead.

I assume we would generate the ChangeLog file at make dist time only.
Perhaps we can adapt the method used by coreutils, but adapted for hg
instead of git.

| Anyone who is interested in every detail can read the hg log,

That is true for people who have access to the hg archive.  That is
not necessarily true for people who pick up an Octave release in a
tarball, so it could still be useful to have a generated ChangeLog
file.  But certainly not as useful as looking at a changeset file
which has the log message and the diffs together.

So if we can write good commit messages that can be used to
automatically generate a ChangeLog file for the releases, I'm
certainly in favor of changing the way we work.

jwe