ChangeLog formatting?

[Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx>]

Should we agree on some "rules" for ChangeLog entries?

Peter just made this one:

        * 16033: Pavel Roskin <proski@xxxxxxx>:
          Src/Builtins/rlimits.c: Undefine RLIMIT_RSS if it's equal to
        RLIMIT_VMEM to avoid duplicate case value.
          aczsh.m4 (zsh_LARGE_FILE_SUPPORT): Ignore output of getconf
        if it returns "undefined".

This manages in one swoop to illustrate several things:  Someone else sent
the patch, but Peter committed it; the same patch made changes to different
files for different reasons; and there's a specific section of one of the
files to which the change applies.

We're particularly inconsistent about how we credit other contributors (I'm
guilty of this too).  Examples:

        * Adapted from Stefan Dalibor, 16043: Src/utils.c: checkrmall()
        must not print to shout when shout's not valid.

        * Bart: 16038 and 16041: Src/cond.c, Src/loop.c: for caching of
        compiled patterns: remember that singsub() might modify the string
        it gets, compare with unmodified string

        * Norbert Koch: 15954: Doc/Zsh/arith.yo:
        fix inconsistency of variable name in example.

        * 15562, Akinori Musha: 15559, 15563: Completion/BSD/Command/_chflags,
        Completion/Unix/Command/_chown, Completion/Unix/Command/_sysctl:
        new BSD completion and fix _chown for symlinks

        * 15278 (Sven), 15390: Completion/Unix/Command/_mount,
        Completion/Unix/Type/_path_files: more Cygwin support
        15278 was accidentally committed by me

There are even more variants if you look at ChangeLog-3.1.    However, since
-3.1, we've mostly been putting the name first and the article number after
it.  In the case of "16038 and 16041", this doesn't work out so well; I was
responsible only for 16038, but it's hard to tell that from the log entry.

With respect to different reasons for different files, most of the time the
files are still all listed together after the article, and the descriptions
are all grouped together as well, and it's up to the reader to figure out
which ones go together.  I only found one previous example of breaking up
the list of files:

        * 15060: Test/A02alias.ztst: Change expected return value to
        account for 15050.

        * 15060: Test/Y01completion.ztst, Test/Y02compmatch.ztst,
        Test/Y03arguments.ztst, Test/comptest: Abandon the tests during
        the %prep section if the zpty module can't be loaded.

I can't find any examples to compare to "aczsh.m4 (zsh_LARGE_FILE_SUPPORT)".
That sort of thing has always been relegated to the descriptions before.

Finally, as you can see from the above, examples, we're also inconsistent
about capitalization, whether there is a newline after the colon at the
end of the list of file names, and at what column the lines should wrap,
but those are much less significant details.

Of course I probably wouldn't even be bothering to mention this if not for
difflog.pl ... but as long as I'm making some kind of stab at parsing of
ChangeLog entries, it'd be nice to have some limits on what the parser has
to handle.

Comments?

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net