CPAN Wants You!
Want to contribute to your favorite CPAN module, or maybe create your own, but don’t have the foggiest idea how to do it? Here are a few notes, tips, tricks, and links that might help you get started.
PAUSE id
While bringing awesome street cred, having a PAUSE id is strictly necessary only if you want to maintain or co-maintain a module. If you just want to contribute code, you’ll perfectly be able to do without, as it will usually be done via patches submitted to a bug tracking system, a code repository or using good ol’ email.
Becoming a co-maintainer
Becoming the co-maintainer of a module gives you the power to upload authorized releases of the modules on CPAN. To become one, the maintainer of the module simply has to promote you as such on PAUSE.
Creating a new module
You want to create your own module? Excellent! But before you do it, make sure that you . . .
- you verified on CPAN that there’s not already a module that already scratch that particular itch.
- You made sure that the module uses a descriptive and pertinent namespace.
Once this is done, go ahead: log on PAUSE and register the module.
Adopting an abandoned module
There’s a module apparently abandoned by its owner that you’d love to take over? The procedure for that is given in the CPAN FAQ, and it can be boiled down to:
- Try to get in contact with the current maintainer.
- If you reach him or her, make puppy eyes and ask if you can take over.
- If they are agreeable, they will flip over the maintenance of the module to you on PAUSE, and that’s all there is to it.
- If you tried their email addresses, poked around in mailing lists, forums and other places without any luck, wait a little bit (a couple of weeks) and contact the PAUSE admins.
Module created! How do I upload releases, now?
You upload new versions of a module via the PAUSE interface or via ftp.
Alternatively, and more conveniently, you can also use the cpan-upload script provided by CPAN::Uploader.
Bug Tracking
Contributing to a module means fixing bugs or implementing new enhancements. To find those, who are you gonna call? The Bug Tracker!
rt.cpan.org
By default, every module on CPAN has a bug tracking queue on rt.cpan.org. For example, the one for Git::CPAN::Patch is at https://rt.cpan.org/Public/Dist/Display.html?Name=Git-CPAN-Patch.
Bug reporting can be done via the web interface, or by sending an email to bug-module@rt.cpan.org (e.g., [email protected]).
…or somewhere else
Sometimes, the module’s maintainer uses a different bug tracking system. You’ll typically find it mentioned in the POD, or in the META.yml:
$ curl -L https://search.cpan.org/dist/Git-CPAN-Patch/META.yml | \
perl -MYAML -0 -E'say Load(<>)->{resources}{bugtracker}'
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Git-CPAN-Patch
If you don’t feel inclined to dig into META.yml for information, there is a Greasemonkey script that will do it for you, and automatically add a link to the bugtracker (along some other goodies) on the module’s CPAN page.
…or here, there and everywhere
What if the bugs are kept on rt.cpan.org, and on the local bug tracking system of Github, and a few other places? You can either follow them manually, or you can get funky and experiment with SD, a peer-to-peer ticket tracking system that can sync with and merge the information of several online bug tracking systems. SD, it goes without saying, can be found on CPAN as App::SD.
Code Repository
Most, but not all, modules have a public code repository somewhere out there. Just like for the bug tracking system look for it in the POD, or in the META.yml. It will be displayed on the module’s cpan page as well.
$ curl -L https://search.cpan.org/dist/Git-CPAN-Patch/META.yml | \
perl -MYAML -0 -E'say Load(<>)->{resources}{repository}'
git://github.com/yanick/git-cpan-patch.git
<singing name=”Adam West”>Na na na na, Na na na na, GitPAN!</singing>
Thanks to Schwern, all CPAN distributions now have a GitHub repository tracking its releases. They can all be found under the GitHub gitpan account, and follow the pattern https://github.com/gitpan/Git-CPAN-Patch.
Git::CPAN::Patch
Speaking of Git::CPAN::Patch, you can use its set of scripts to ease the creation of CPAN-related git repositories. It also includes scripts to send patches directly from your local repository to a rt bug queue.
5 Comments. Leave new
Thanks Yanick. That really simplifies and clarifies the process. I had no idea it was all so simple.
Yup, when you know where to send patches, the Perl ecosystem always has been fairly easy to enter. But the arrival of Git simplified it to even greater levels. By now, sending a patch to any module can be as simple as (I hope the comment doesn’t murder the formatting here):
$ git cpan-init Some::Module
$ git checkout -b mypatch
…hack hack hack…
$ git rebase -i cpan
$ git cpan-sendpatch
For more details, see my original Git::CPAN::Patch blog entry (https://use.perl.org/~Yanick/journal/38180), and — if you subscribe to it — the related article in the Perl Review (https://theperlreview.com/, edition 5.1).
Great Job. I was looking forward to this post. The biggest piece of the puzzle I was missing was PAUSE.
don’t forget Dist::Zilla https://search.cpan.org/~rjbs/Dist-Zilla-1.100160/lib/Dist/Zilla.pm
Good point. A little more than a year ago, I gave it a whirl and, although it was very promising, it wasn’t exactly scratching the itch in the way I wanted — so I ended up trying to come up with my own solution (https://use.perl.org/~Yanick/journal/37852).
But I just gave a second look at Zilla over the week-end and, by Joves, it’s getting there. I’ll give it a new try, but something tells me I’ll soon be kissing poor Dist::Release goodbye and join the enemy camp. :-)