How not to do a Changes file

Here's how to not do a Changes file:

http://search.cpan.org/src/FELICITY/Mail-SpamAssassin-3.1.5/Changes

That tells me nothing about whether I want to upgrade my SpamAssassin install. :-(

Oh, look, I wrote about this before, and how great Tim Bunce's Changes files are.

Categories:

5 Comments

notbenh said:

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?

Chris Dolan said:

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

Andy Lester said:

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.

Chris Dolan said:

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.

Justin Mason said:

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.

Leave a comment

About this Entry

This page contains a single entry by Andy Lester published on February 27, 2008 11:33 PM.

Free up a few gigabytes of space on your Mac was the previous entry in this blog.

The worst way to shorten names is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

Other Perl Sites

Other Swell Blogs

  • geek2geek: An ongoing analysis of how geeks communicate, how we fail and how to fix it.