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.