Marking modules as 'available for adoption'

CPANPAUSEadoptionpermissions Wed 7 August 2013

PAUSE supports an informal mechanism for flagging that a module is available to be taken over, or to flag that you'd like help. In this article I'll outline the mechanism, and point out some things to be aware of.

At the 2013 Perl QA Hackathon, the 'toolchain gang' produced The Lancaster Consensus, a document which describes common / proposed standards and practices. One section covers a way to flag abandoned modules and modules requesting help.

If you're not familiar with the PAUSE Permission model, you could read the documentation for PAUSE::Permissions, or the slides from my lightning talk on PAUSE Permissions. My PAUSE id is NEILB. If I upload a new distribution to PAUSE, containing two new modules (ie never before seen on CPAN), then PAUSE gives permission for those modules to NEILB and no-one else. Now I can upload those modules, but if anyone else does, their upload won't be indexed.

When you grant co-maint to someone, their PAUSE id is given co-maint permissions on each module. There are some pseudo user ids used to flag various special cases. For example user P5P has co-maint permissions on some core modules. There are three such pseudo-users that are used to flag that a module can be adopted, or that the owner would like help:

For ADOPTME, anyone interested in taking over the module just needs to email the PAUSE Admins, and they'll be granted ownership ('f' permissions).

If you want to mark one of your distributions as available for adoption, it's not entirely clear whether you should use ADOPTME or HANDOFF, but David Golden has clarified in a way that might be useful:

As noted in the Lancaster Consensus, the PAUSE permissions model applies to modules, but modules are released in distributions. In the future PAUSE will (hopefully) support a dist-based permissions model.

But in the meantime, when using ADOPTME, HANDOFF, and NEEDHELP, you need to be careful to think about distributions vs modules. What is the correct interpretation when some but not all of the modules in a distribution have the ADOPTME permission?

You also need to watch out for the case where a .pm file defines more than one package. When you do this, PAUSE gives you permissions for all packages defined in your dist, not just the ones that have their own files. An example of this is Math-Cephes, Shlomi Fish's distribution. Here are the permissions:

ADOPTME Math::Cephes
ADOPTME Math::Cephes::Complex
ADOPTME Math::Cephes::Fraction
ADOPTME Math::Cephes::Matrix
ADOPTME Math::Cephes::Polynomial

If you click on the Math-Cephes link above, you'll see that Math::Cephesc is provided in Math/, which also provides Math::Cephes.

There are only 11 distributions that have partial ADOPTME coverage; where the author isn't deceased, I've emailed them asking what their intention was. In the meantime my interpretation will be that if the 'top-level module' in a dist has ADOPTME, then the distribution can be treated as if it has ADOPTME on the distribution.

So the following dist I think shouldn't be treated as adoptable:

      ADOPTME HouseURL

But the following is probably ok:

      ADOPTME Palm::Magellan::NavCompanion

I'm also going to see what the PAUSE Admins think.

comments powered by Disqus