Adopt a CPAN module

CPANadoption Wed 24 July 2013

Adopting a module on CPAN is a good way to learn the process of creating, releasing and maintaining a CPAN module. If you fancy the challenge, there are plenty of modules out there with outstanding bugs. Or maybe there's a feature you'd like to add to one of the modules you use? In this post I'll outline the process I've used to adopt modules, then describe each step in more detail. Let me know how this can be improved.

Here's the process I follow:

While working on my reviews I've adopted 15 distributions to date. Every time I do a review I seem to end up adopting another dist.

This process is largely based on the 'taking over' section of the PAUSE documentation. If you're interested in adopting a module, you should read that too.

Find a module

The first place to look is the modules you're already using. Are there any which have outstanding bugs and that haven't been released in at least 6 months? Having identified a number of candidate modules, look at each author's 'home page' on MetaCPAN: have they released anything in the last year or so?

If not, look for modules with a lot of bugs, or modules that are used by other modules.

For your first time, pick a dist that only contains one or at most a small handful of modules.

Fork it on github

Go to GitHub and see if the module is already there. Type the module name in the search box (at the top of the page). If there are a lot of results, look in the sidebar at the left, headed Languages and click on Perl to restrict the search.

If you're lucky, the author / maintainer already has a repository (we'll use 'repo' from now on) on github. If the module is old enough, you'll find a repo in the gitpan user. Gitpan is an automated account that was set up by Michael Schwern. It created repos for all distributions on CPAN at the time. Check whether gitpan's version is the latest version on CPAN.

If you can't find it on github at all, create a new repo then import the latest version of the dist from CPAN.

Fix one or more bugs

Have a look in the list of bugs for the module / dist, and pick one or more to fix.

If there's a new feature you'd like to see in the module, start off by adding an issue requesting the feature.

Fix the bug(s) and / or implement the new feature. Look at any other outstanding bugs, and see whether you could address any of them. Don't reformat the code to your preference's, follow the style of the existing code.

Push the changes to your repo.

Follow up in the bug tracker

Add a comment to the bug(s) saying that you've fixed it / them, and include a link to your repo.

Offer to do a release

When posting to the tracker, say that you'd be happy to do a release, if the current maintainer is too busy. Be polite. This module may once have been their pride and joy. They may just be busy with other projects or real life right now, so don't act like it's your right to be given co-maintainership.

At this point the maintainer may 'wake up' and do a release. They may intend to do a release, but get distracted again. Be patient. And polite.

If you get no response, try email

Bug reports (via RT) get emailed to the author's contact email address. People don't always remember to update their email address, so your email might be going nowhere.

Look for them online, using google, LinkedIn, Google+, etc. Send them an email, referring to the bug(s) you fixed and your repo. Offer to do a release, if they'd be happy to give you co-maint.

If you get no response to these emails, then you need to practice your patience again.

After two week, try again

Try all the email adresses you have again. But now try pinging various parts of the perl community to see whether anyone is in contact with the current maintainer:

If you've got multiple email accounts, try sending from each of them: the first email(s) you sent might have been classified as spam.

After one month, email the PAUSE admins

After a month has passed, send email to the PAUSE admins, asking to be granted co-maintainer status for the dist, copying the email address(es) you have for the current maintainer.

Summarise the things you've done and give a link to your repo. List all of the modules in the dist, and give the current maintainer's PAUSE id. If the author hasn't released anything for at least a year, then mention that in your email, and include a link to their MetaCPAN page.

Browse the PAUSE admins' email archive and look for examples. Someone asked me for an example email, so here's a template:

Dear PAUSE Admins,

Can you give me co-maint for Foo::Bar please? This was written by Fred Bloggs (FREDB), and last released in July 2006.

I emailed Fred on 17th June, and again 2 weeks later, but haven't had any reply. I tried to track Fred down via LinkedIn / Google+ / Twitter / Facebook but without success. I've cc'd him on this email.

I've cloned the github repo and have fixed some / all of the bugs in RT. If I get co-maint, I'll release my fixed version, and also add metadata for the repo and license type, and tidy up the Changes file, following the Questhub quests.


The PAUSE admins are regular people like you and me. And from what I can tell, they're also very busy: please be respectful of their time and make things as easy for them as you can.

Don't be surprised if you finally get an email response from the maintainer at this stage.

comments powered by Disqus