Re: ChangeLogs

[John W. Eaton]

On  5-Jan-2009, Thorsten Meyer wrote:

| 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-
|         [...]
|         src/ov-scalar.h, src/ov-str-mat.cc, src/ov-str-mat.h, src/ov.h:
|         remove valid_as_scalar_index
|         [f00578b495e9]

Hmm.  It is bad that the default format breaks filenames as that would
cause trouble for searching.  That should be fixed so that filenames
are never split.

| 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?

The changelog style for Mercurial is apparently just a template
definition, so I think that should be possible.  But even so, I don't
see the problem.  We don't have to write the list of files by hand,
and in a way it is better than the current hand-edited files because
it lists all files that were changed (I'll bet we often omit some in
the hand-edited log entries).

| 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

Yes, to get something that approximates ChangeLogs that follow the GNU
conventions, we would need to write something like you show.  I would
do it like this:

  one line summary

  * file1.cc (function): What changed.
  (other_function): Other change.
  * file2.cc (function): Another change.

Then it would show up in the generated changelog file as

  2009-01-06  John W. Eaton  <address@hidden>

          * file1.cc, file2.cc:
          one line summary

          * file1.cc (function): What changed. (other_function): Other change.
          * file2.cc (function): Another change.
          [f7a80a86bc8f] [tip]

For me, I think that is close enough if it also simplifies the way we
work.

The disadvantages I see are that this amount of information can't
easily be entered at the command line (with hg commit -m "...").  So I
would probably work like this:

  * make some changes

  * edit a temporary file that has the log message in the format shown
    above, but without any leading spaces

  * commit the change with "hg commit -l tmp-file"

Unfortunately, the Emacs ChangeLog mode is not quite the right thing
for the format of the log message (I would rather not give up M-x
add-change-log-entry...), but one could just use that then strip out
the date/user information and the leading whitespace.  It would be easy
enough to write a simple function to do that, and probably not much
harder to customize the Emacs ChangeLog mode to make editing these log
entries easier.  If you are not using Emacs, then I suppose you are
either already editing ChangeLogs entirely by hand, or you could adapt
whatever tools your editor has in a similar way.

jwe