Recently there was some interesting discussion of using YAML to format CPAN ChangeLog files to make them both human- and machine-readable.
I decided to give it a try in my most recent distributions and I've decided I like it a lot. I didn't try to stick to anybody else's schema, but instead just tweaked my usual ChangeLog writing habits a bit.
Most importantly, though, I added a t/00_local_changelog.t that looks like the following. (The "00_local_" in the filename is my convention for files that do not get included in MANIFEST)
#!perl use warnings; use strict; use YAML qw(); use File::Slurp qw(); use Test::More tests => 5;
ok(-f 'Changes', 'change log file exists'); my $content = File::Slurp::read_file('Changes'); SKIP: { if ($content !~ m/yaml/ixms) { skip 'Changelog does not claim to be YAML', 4; } my $data = YAML::Load($content); ok($data, 'changelog has YAML data');
my %good = ( versions => 1, dates => 1, summaries => 1, ); my %alltags; for my $version (sort keys %{$data}) {
if ($version !~ m/\A \d+\.\d+[.\d_]* \z/xms) { diag 'Bad version number: ' . $version; $good{versions} = 0; }
my %release = map {%{$_}} @{$data->{$version}};
if (!$release{Released}) { diag 'Missing release date for ' . $version; $good{dates} = 0; } elsif ($release{Released} !~ m/\A never /ixms && $release{Released} !~ m/\A 20\d\d [ ] (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [ ] \d\d \z/xms) { diag 'Bad release date for ' . $version . ': ' . $release{Released}; $good{dates} = 0; }
if (!$release{Summary}) { diag 'Missing summary for ' . $version; $good{summaries} = 0; }
%alltags = (%release, %alltags); } ok($good{versions}, 'version numbers are all valid'); ok($good{dates}, 'release dates are all valid'); ok($good{summaries}, 'releases have summaries'); diag "Tags used: @{[sort keys %alltags]}"; }
You might also want to have a look at Module::Changes, especially the bin/changes program.
All my recently uploaded distros now contain YAML-based Changes files.
I'm also checking the YAML Changes file, but do it from within shipit using ShipIt::Step::CheckYAMLChangeLog.
Re:Module::Changes
ChrisDolan on 2007-11-23T01:30:45
Interesting, I had not heard of ShipIt. I'll look at it.
I looked at your changelog and I have to say in all modesty, I like my own syntax a lot more than yours. I think my choice to make version numbers the key of the hash increases the readability of the file dramatically.
I'm definitely in favor of standardization, but if it's going to be YAML (instead of more interoperable XML) then it had better emphasize the YAML advantage of human-readability.
Re:Module::Changes
hanekomu on 2007-11-23T09:00:23
In an earlier version, I had the version numbers as the keys. Didn't work out very well - there were complaints of it all being too indented. Also, now I can verify the validity of the Changes file with a Kwalify syntax.
But it doesn't matter - you can just write a new parser and a new formatter for Module::Changes. I'd have to change the bin/changes program to take args for different parser and formatters (maybe get them from some ~/.changesrc), but that's easy.
