Ali Anari

Lessons learned publishing my first CPAN module

So you want to join the ranks of thousands of other #perl hackers and release
something to the community? I just developed my first standalone Perl module at
Crowdtilt called
WebService::NationBuilder,
and the process was actually a lot more straightforward than I thought it would
be. Keep reading to find out how simple it really is to write your own module
and become a published CPAN (Comprehensive Perl Archive Network)
author!

PAUSE then play

Head on over to PAUSE, the Perl Authors
Upload SErver and register your very own account using this
form. Your account
will get its own directory (mine turned out to be authors/id/A/AA/AANARI)
where your uploaded distributions will be indexed and rapidly propogated
across CPAN and its mirrors thanks to some of the fast rsync stuff the PAUSE
workers have developed. Don’t let the old-school feel of the PAUSE site fool
you, it’s a serious platform that was created by Andreas Koenig in 1995 and
has been closely maintained since. For the ever curious, you can dive into the
source GitHub repo here.

My::Module v0.0001

You may want to follow some naming convention
to make sure your module fits in with everything else already on CPAN. Mine was
simple because WebService is a standard namespace for Perl HTTP client libraries,
but you can always ask the good folks over at modules@perl.org
if you’re ever unsure.
Versioning
can be tricky because Perl honors backwards compatibility, so I recommend using
your first digit for Major version, two digits denoting your Minor version,
and two final digits for your bugfix or incrementing version number: 1.2501
means v1.25.1. Most importantly, don’t switch version number schemes for a
published module or your users won’t know in advance the right format to request.

dzil to the rescue

Dist::Zilla automates away common
distribution tasks, and we love using it here at
Crowdtilt. The dzil website is chock
full of useful tutorials, plugins, and other goodies that helped me get up and
running in no time. Run dzil setup and enter your PAUSE credentials, and
you’ll never have to manually upload your releases again! Now invoke dzil new
and do what you do best – write some killer Perl code.

PODs you can trust

Perl’s documentation system is POD
(Plain Old Documentation) and it’s easy to get up and running if
you’ve ever used any other human-readable documentation format like Markdown or
YAML. You can even generate your repo’s README.md from POD using a dzil
plugin, but for WebService::NationBuilder I created separate documentation
files for now. You should definitely spend the extra few minutes and define
PODs so that your beautiful docs show up on CPAN, or in the terminal when one of
your users runs perldoc against your module.

D (deploy) day

Run dzil release and your shiny new module is on its way for the world to see!
You can view your distribution’s page on MetaCPAN
within an hour (usually 30 minutes), as this site updates very quickly from
PAUSE. Now you can install your distribution from CPAN using your favorite CPAN
client like cpanm, although you might need to wait until your distribution
reaches your configured CPAN mirror.

Perl IRL?

Many of the talks at Perl conferences involve authors talking about their work,
because after all, who is better qualified to help others use your module than
you? For the non-public-speaking-inclined, there’s always the small casual
setting of your local Perl user group (you can find one near you on the Perl
Mongers website.