ChangeLog formatting?

ChangeLog formatting?

[Bart Schaefer]

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

Peter just made this one:

        * 16033: Pavel Roskin <proski@gnu.org>:
          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   

Re: ChangeLog formatting?

[Oliver Kiddle]

Bart Schaefer wrote:
> 
> Should we agree on some "rules" for ChangeLog entries?

> 
> We're particularly inconsistent about how we credit other contributors (I'm
> guilty of this too).  Examples:
>
>         * 15562, Akinori Musha: 15559, 15563: Completion/BSD/Command/_chflags,

I would vote for this format for credited contributions. By putting the
name before message numbers, it can be inferred that the first message
number was by whomever committed the change without their having to
repeat their own name. First names only should be suffcient for the
usual suspects (as is common at the moment) and e-mail addresses are
perhaps more information than anyone will ever use.

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

Here, it looks like the contributed change was modified slightly in a
way that is too insignificant to post. So we need a way to cover this.

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

Splitting these as per the example more often is perhaps a good idea
then.

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

My votes here are for wrapping so the maximum line is 79 characters. No
newline after the colon unless it could only be followed by about one
word before wrapping at the line end, no initial capitalisation to
avoid the temptation to capitalise the first letter of a function name.
If we don't capitalise, then no final full-stop for consistency with
that. As you say though, these issues are less significant so I don't
care much and will happily defer to anyone else's suggestions.

We could also agree on the format of notes added to cvs - some notes
are preceded by the message number and a colon while others are
followed by the message numbr in brackets.

Oliver

Re: ChangeLog formatting?

[Adam Spiers]

Bart Schaefer (schaefer@brasslantern.com) wrote:
> Should we agree on some "rules" for ChangeLog entries?

Yes :-)

[snip]

> Comments?

Would be nice to have a convention for cvs commit log messages too.

Re: ChangeLog formatting?

[Wayne Davison]

On Tue, 23 Oct 2001, Adam Spiers wrote:
> Would be nice to have a convention for cvs commit log messages too.

In what way were you thinking?  I'd be cautious of too much
conformance, but some basic guidelines could be useful.

I personally prefer to customize each file's log message to directly
reflect that's file's changes, and I think most of the log messages
I've seen for zsh are the same way.  I created a perl script to make
this easier for me.  If any of you are like-minded on this, you may
find the following steps useful.

1.  I first diff the changes to create a patch file.

2.  I run "egrep '^Index: ' diff.file" >>cvs.put" to get the names of
all the changed files.

3.  I then edit the cvs.put file to add a paragraph (or whatever)
after each Index: line that describes the changes to that file.

4.  I run the attached perl script (which I also named cvs.put), which
reads the local cvs.put file and commits all the changes with the
associated log messages.  The script also appends the committed
descriptions in a more ChangeLog-like style onto a file named "CL".

5.  I insert the CL file at the start of the ChangeLog file, edit the
entry for brevity and proper format, and commit it.

6.  I move CL to CL.old.

My script also allows you to comment out an Index: line with "#" to
avoid committing a file and it allows you to use the same comment for
multiple files by putting only one comment section after multiple
Index lines.  For instance:

-----
Index: Src/hist.c
Index: Src/builtins.c

Fixed a typo.  (This comment will be used on both of the above files.)

#Index: Src/subst.c

Silenced a compiler warning.  (This file will not be committed until
the above Index line is uncommented.)

Index: Src/Zle/zle_main.c

Frobbed the flebblesnorf.
-----

I hope someone finds this useful.  Be sure to edit in your username
and email address in place of mine in the following script.

..wayne..

---8<------8<------8<------8<---cut here--->8------>8------>8------>8---
#!/usr/bin/perl

$msg = '';
$defer = 0;
@files = ( );
@deferred = ( );

open(IN, 'cvs.put') or die "Unable to read cvs.put\n";
-s IN or die "cvs.put is empty\n";
open(OUT, '>cvs.put.new') or die "Unable to write cvs.put.out\n";
open(CL, '>>CL') or die "Unable to append to CL\n";

chomp($now = `date +%Y-%m-%d`);
print CL $now, "  Wayne Davison  <wayned\@users.sourceforge.net>\n\n";

while (<IN>) {
    if (/^(#*)Index:\s*(\S+)/) {
	&commit;
	push(@files, $2);
	$defer = 1 if $1 ne '';
    }
    else {
	die "Malformed cvs.put file -- line w/o Index line:\n$_" unless @files;
	$msg .= $_;
    }
}
&commit;

close(OUT);
close(IN);

rename('cvs.put', 'cvs.put.old');
rename('cvs.put.new', 'cvs.put');

print "\nDeferred puts for: @deferred\n" if @deferred;
exit;


sub commit
{
    return if $msg eq ''; # Multiple adjacent Index lines use the same msg
    if ($defer) {
	$defer = 0;
	push(@deferred, @files);
	print OUT '#Index: ', join("\n#Index: ", @files), "\n", $msg;
	undef @files;
	$msg = '';
	return;
    }
    $msg =~ s/^\n+//;
    $msg =~ s/\s+$//;
    if ($msg eq '') {
	print "ERROR: Incomplete message for: @files\n";
	push(@deferred, @files);
	print OUT 'Index: ', join("\nIndex: ", @files), "\n\n\n\n";
	undef @files;
	$msg = '';
	return;
    }
    open(MSG, '>cvs.msg') or die "Unable to write cvs.msg\n";
    print MSG $msg, "\n";
    close(MSG);
    $msg =~ s/^/\t/mg;
    print CL "\t* ", join(', ', @files), ":\n", $msg, "\n\n";
    system "cvs commit -F cvs.msg @files";
    unlink('cvs.msg');
    undef @files;
    $msg = '';
}
---8<------8<------8<------8<---cut here--->8------>8------>8------>8---

Re: ChangeLog formatting?

[Bart Schaefer]

On Oct 23,  4:37pm, Wayne Davison wrote:
> 
> On Tue, 23 Oct 2001, Adam Spiers wrote:
> > Would be nice to have a convention for cvs commit log messages too.
> 
> In what way were you thinking?  I'd be cautious of too much
> conformance, but some basic guidelines could be useful.

For zsh, I generally try to keep my commit log messages less than one line
long so I can easily pass them in the -m option of "cvs commit".  If you
want the full story, read the ChangeLog.

Normally I'd just let CVS bring up the editor for each directory and type a
description of each file as they're shown to me, but I'm committing to the
cvs.zsh.sf.net server over a slow enough link that I get timeouts if I don't
keep the messages very brief and let the whole process run in one swoop.

Re: ChangeLog formatting?

[Clint Adams]

> For zsh, I generally try to keep my commit log messages less than one line
> long so I can easily pass them in the -m option of "cvs commit".  If you
> want the full story, read the ChangeLog.

I like "article number: short description", and I prefer to commit all
files at once.  Thus the ChangeLog entry, the cvs log entry, and the
diffs all correspond to the patch posted to the mailing list.

Re: ChangeLog formatting?

[Adam Spiers]

Clint Adams (clint@zsh.org) wrote:
> I like "article number: short description", and I prefer to commit all
> files at once.  Thus the ChangeLog entry, the cvs log entry, and the
> diffs all correspond to the patch posted to the mailing list.

That gets my vote.  Related changes are best committed atomically,
IMHO.