How not to do a Changes file

I agree, your svn log is one thing, changes file something else. I tend to think of the changes file as the summary of your log in a sentence, possibly a paragraph. But that just makes me wonder, what is more important? There intent is completely different access to the same information?

How about this style: http://search.cpan.org/src/CDOLAN/Test-Virtual-Filesystem-0.12/Changes

It's YAML, written with enough whitespace to make it human readable. And I can summarize it pretty easily with this ugly-but-concise command:

perl -MYAML -0 -ne'$c=Load $_;for $v (sort keys %$c){print "$v\t ",map({$_->{Summary}} @{$c->{$v}}),"\n"}' < Changes

Which yields:
0.01 initial release
0.02 Backward compatibility, xattrs, symlinks
0.03 Important bug fixes
0.04 Renamed test_* methods from v0.03; Subclassing; Bug fixes
0.05 Fix for non-English localized Perl
0.06 Perl prereq to 5.8.0; new truncate, symlink, a/m/ctime tests
0.07 Fix nested symlink test for Linux; Forgive skew between clock and disk timestamp
0.08 Added rename tests
0.09_01 Speculative fixes for platform inconsistencies
0.10 Fixes for Win32
0.11 Fix for Solaris
0.12 Fix for Cygwin

That's a slick trick, Chris.

My concern with most change logs is that it seems to put the ease of maintenance as the #1 priority, instead of how easy it is for the user, the reader, to find the information she needs to know. I want my change logs to be about the user first & foremost. I want the human-based annotations.

Andy,

Agreed. I tried to achieve that goal by 1) including a summary for every release and 2) organizing my changes as Feature, Incompatibility and Fix (in that order) and 3) keeping every entry to one line of about 70 characters, which is the hardest part.

For those of you leaving comments -- be warned that this appears to be an old blog post from 2006, and already has a pretty well hashed-out comment thread:

http://use.perl.org/~petdance/journal/30809

Took me a while to figure that out, I knew it seemed familiar.