Re: ChangeLog formatting?

[Wayne Davison <wayned@users.sourceforge.net>]

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