Chisel

I’ve converted a number of distributions from $something to Dist::Zilla for release management, and every time I forget something … so this time I’m making notes as I go along.

Worst case, future-me will thank present-me (or will that be past-me?)

What follows is the transition for WebService::NotifyMyAndroid. It might have a couple of places where common sense needs to be applied, but it’s ‘good enough’.

Prerequisites

I’m assuming you’ve already got a perl distribution and that you’re managing it with git.

I’m also asssuming you already have Dist::Zilla installed.

Custom dist.ini

My distributions are minted using this file as a template for dist.ini.

Let’s Go!

Just to be safe we’ll work from anew branch based on our current master:

git checkout master
git pull --rebase
git co -b dzil master

Now we’re ready to rock and roll!

Create our dist.ini

I’m ‘lazy’ and don’t like to write mine by hand, so I’ll let Dist::Zilla do the work for me:

dzil new WebService::NotifyMyAndroid
mv WebService-NotifyMyAndroid/dist.ini .
rm -rf WebService-NotifyMyAndroid/
git add dist.ini

If you don’t already have it, it’s worth adding

[AutoPrereqs]

to your dist.ini.

Make the build process happy

To make ‘CheckChangesHasContent’ happy add the following before the most recent release:

{{$NEXT}}
      Convert to Dist::Zilla

then add it to the staged area:

git add Changes

Cleanup some files

Get rid of the files that we used to manage ourselves manually:

dzil build --notgz 2>&1 |grep 'multiple times' |cut -d' ' -f 5

If you don’t get any output at all it’s worth re-running without the piped-cut to make sure it didn’t abort the build earlier than expected.

The output should look something like this:

MANIFEST
META.yml
README
Makefile.PL

Checking the files, all the files, bar README, are autogenerated. Looking at the README we decide we’d like to keep this file, but under a different name:

git mv README README.install

Then remove the other files:

for f in $( \
  dzil build --notgz 2>&1 \
    |grep 'multiple times' \
    |cut -d' ' -f 5 \
); do
    # make sure we don't git manage them
    git rm -f $f;
    # make sure they aren't artifacts form previous builds
    rm -f $f;
done;

We also no longer need these files:

rm -rf blib/ _build/
git rm Build.PL
rm -rf blib/ _build/ Build

Nor do we want any META files hanging around:

for f in MANIFEST* *META*; do
   git rm -f $f 2>/dev/null; \
   rm -f $f; \
done

Dist::Zilla generates build directories and files based on our dist name; let’s ignore them:

echo '/WebService-NotifyMyAndroid*tar.gz' >> .gitignore
echo '/WebService-NotifyMyAndroid*/' >> .gitignore
echo '/.build/' >> .gitignore
git add .gitignore

Deal with versioning

Anywhere we’ve manually specified $VERSION we should simple remove it:

# remove manual version setting in thse files
vim $(/bin/grep -rl 'our $VERSION' lib/)
# git status
# git add <files we edited>

Add missing abstracts

To list files with missing abstracts simple do he following:

dzil build --notgz |grep "couldn't find abstract" |cut -d' ' -f 7

You should edit these manually and add an appropriate:

# ABSTRACT: <one line abstract>

line to each of the files. I prefer to put my comment at the end of the file (but before the END marker:

1;# Magic true value required at end of module
# ABSTRACT: Perl interface to Notify My Android web API
__END__

Don’t forget to ‘git add’ any files you’ve edited.

Cleanup POD

Assuming you also use the PodWeaver plugin, you should work through all the perl and POD files in your distribution to make the following alterations:

Module NAME and abstract line

No need to add the NAME section:

=head1 NAME

WebService::NotifyMyAndroid - Perl interface to Notify My Android web API

Version numbers in POD

No need to manually specify and update the VERSION block:

=head1 VERSION

This document describes WebService::NotifyMyAndroid version 0.0.3.

Licence and Copyright

This is added automatically, so you can remove any of these sections

Authors and Contributors

In lieu of a ‘Contributor plugin’ you may wish to promote your contributors to authors - otherwise you end up with them in different parts of the woven POD.

Make sure you specify your authors in dist.ini:

author           = Steve Huff <shuff@cpan.org>
author           = Chisel <chisel@chizography.net>

and remove any ‘AUTHOR’ and ‘CONTRIBUTOR’ sections in your POD.

Custom step

I did this just for this distro, just to cleanup:

git rm README.mkd

Commit And Push

We’re in the final stages now; time to push our work to our remote to keep it safe:

git commit -m 'Convert dist to use Dist::Zilla'
git push -u origin master

Test a release candidate

From my experience, you’ll always miss something obvious, or silly when converting to Dist::Zilla, so it’s probably best to release a developer release of the module until there’s enough feedback from CPAN Testers for us to fix everything, or decide it’s good enought to release to the world:

dzil clean && \
V=0.0.5_01 dzil release

Keep Testing

If you’re anything like me, you’ll miss a few things on your first release, no matter how careful you are. You’ll also probably find you get failures for unexpected and surprising reasons.

Don’t despair, just chip away at the niggles until you have a developer release that shows as a pass for all (or near enough) reports on CPAN Testers.