Some modules on CPAN were created by the same person who has always released it. But there are plenty which have been through many different hands, and which perhaps are released by a number of different project / team members. How should those different people be acknowledged? This post was prompted by IRC discussion with RJBS and GENEHACK, and Rik's blog post where he proposed that MetaCPAN should show the owner of a dist rather than the person who last released it.

I started this thinking I was going to propose one thing, but by the time I'd written it, I'd changed my mind.

Dramatis personae

Who are the people who might be involved in a module?

The person who initially created the module. Let's refer to them as the creator . They might not have done the first CPAN release, and might never have done any CPAN releases.

The module might be based on a published algorithm (as with Text::Levenshtein, which implements Vladimir Levenshtein's algorithm), or someone's blog post (eg Constant::FromGlobal, which Yuval Kogman wrote, inspired by a blog post by Adam Kennedy). Let's refer to this person as the designer .

The person who did the first release to CPAN. Let's call them the first releaser , though I'm not sure if it's worth distinguishing this from the other roles here.

The person who wrote most of the code in the current release of the module on CPAN. For example, PANDICH did the initial release of Lingua::EN::Numbers in 1999, but then SBURKE took it over and completely rewrote it. So I consider Sean to be the author . Possibly should use a different term like implementer for this role, for reasons that will become clear below.

The person who is the current owner of the module's namespace (the PAUSE id that has the 'first come', or 'f', permission, in PAUSE's permissions model). This may not be the person who did the most recent release, and in fact they might have never released it.

The copyright holder , which is often but not always the author. Mostly it's an individual, but sometimes it's an organisation.

The person who did the most recent release to CPAN. This might be a different person from any of the above. For example, SHLOMIF recently adopted AUDREYT's Object::Declare. Shlomi did the most recent release, but all previous releases were done by Audrey, and she has retained ownership. Let's call them the last releaser .

People who have permission to do releases to CPAN, but aren't the owner. Ie co-maint . They may never have done a release. For example, Object::Declare (from the previous point) could also be released by CLKAO, JESSE, and NUFFIN, but they never have.

People who have submitted bugs, suggestions, patches, pull requests, and other useful input. Typically referred to as contributors .

People who have released CPAN distributions that rely on this one. Let's call them dependents (it's really the distributions that have a dependency, but let's not split hairs).

People who use the module, whether in scripts, one-liners, DarkPAN modules, and in other ways. We'll call them users. They contribute indirectly: discussions on IRC, PerlMonks, blogs, and elsewhere can lead to bug reports and suggestions.

Those are all the roles I can think of right now, but no doubt I've forgotten some. Suggestions for better labels for the roles are welcome, as I just pulled these ones out of my, er, hat.

Where and how are those recorded?

The author field in the distribution's metadata takes a list of people (eg author => [ 'Ken Williams <kwilliams@cpan.org>' ] ). The doc (for CPAN::Meta::Spec) says it's for "the person(s) to contact concerning the distribution". I generally haven't added myself to the author list for dists I've adopted, because I think of author as per my definition in the previous section. But given this definition I probably should have.

The AUTHOR section in the module's documentation. This is free-form text, so I generally record the full author history (eg the AUTHOR section for Lingua::EN::Numbers ), but you see a fair bit of variation in this. The AUTHOR section for DBIx::Class blurs the line between author and contributor, making the point that everyone helped get the distribution to where it is now.

Contributors are often acknowledged in a separate section in the pod, and sometimes in a CONTRIBUTORS file in the top directory of a release. They might be acknowledged in the Changes file. You can also list them in the x_contributors field in the metadata, as described by Gabor.

Who did the most recent release is easily identified from the CPAN Index ( $CPAN/modules/02packages.details.txt.gz ).

The current co-maints and owner of modules are recorded in the 06perms.txt file, which is generated by PAUSE, and can be found at $CPAN/modules/06perms.txt.gz . The history of 06perms.txt isn't recorded, so as far as I know there is no way to get a list of everyone who's ever had permissions for a package name, just those who currently do.

You can find out everyone who has ever done a release of a module by trawling BackPAN.

The COPYRIGHT section (often LICENSE AND COPYRIGHT ) in the pod lists the copyright holder.

Why might you care?

Ok, so we've identified the different people associated with a module, now let's consider it from an end-user's perspective. What are the different scenarios where someone might want to know who's (been) involved with a module? This might affect how we think MetaCPAN should present people alongside the module.

Reporting a bug or suggesting a change. You're after someone who's motivated to do the work and can do a release. Ie the owner and any co-maints. Maybe you've already submitted a bug, and want to know who to chase to see if anything's going to get done about it.

Looking for some functionality on CPAN, and perhaps having found a few options you're wondering "who wrote these?". I think you should really be considering "who is the implementor?", and "who did the most recent releases?" You might think "Oh dear, it's a NEILB module", but if you looked closer you then realise all the important stuff was done by Sean Burke, so you're probably safe.

You want to adopt the module, getting co-maint or possibly ownership, so you can cut a new release. For this you need the owner, if there is one, otherwise you need to talk to the PAUSE admins.

You want to ask a question about the module, from whoever can answer. If the dist has the x_IRC field in its metadata, then MetaCPAN will display a distinct red link in the sidebar, but otherwise people need to know who to look for on IRC, or who to email (if they want to chat rather than raise an issue. Whether that's the right approach is beyond the scope here).

Someone wants to say "thankyou" for the module.

Curiosity about the module, which overlaps which some of the above.

So what should MetaCPAN display?

Right now MetaCPAN displays a large picture of the last person to release the dist. In last year's pull request challenge I got Text-Diff in January. After submitting a PR with some bug fixes, OVID gave me co-maint so I could release the fixes. So now when you look at the module you see:

There are a number of times when this approach doesn't feel right. The one that's bugged me is when I've adopted a module just to fix the dist's metadata, or fix a small bug. I've considered creating a second account with a name like MAINTENANCE for these sort of adoptions, so that (a) I don't get false credit for the module, and (b) it's not listed against my name. But that doesn't address all of the points above.

Furthermore, a lot of the time when people are looking at a module on MetaCPAN, I suspect they're not interested in the author, they're just looking something up in the documentation. In that case I think it's about acknowledging everyone who got the module to this point, not just the person who did the last release. Given all that, I think the following would be an improvement:

Everyone who's done a release (possibly just in the last N years) gets an avatar, and the (f) shows who has ownership (or could show the number of releases in parens after each author. The co-maints line tells you how many other users have co-maint but haven't ever done a release — clicking on it would roll down a list of those users. The contributors would show people listed in x_contributors .

Instead of tiling them down the right-hand side, they could be in a horizontal strip at the top, similar to the way the ++'ers are currently shown. I might play with some more designs and layouts.

I'm still thinking about this, but wanted to post as far as I'd got.

ADOPTME, HANDOFF, and NEEDHELP

The special pseudo-users ADOPTME , HANDOFF , and NEEDHELP , should be handled differently, with MetaCPAN clearly indicating the status. Something like this at the head of the page.

This is similar to the "unauthorised release" warning that is shown if the person doing a release doesn't have at least co-maint for all packages in the release (that are eligible for indexing).

Even if those PAUSE ids have done a release, they shouldn't be treated as authors. Ie they should never be shown in the author panel on the right. I know there are a small number of releases that have been done by ADOPTME , but I think that's an anomaly.

This kind of notice should also be displayed if the metadata flags the distribution as deprecated.

All of the above are things that someone should know about before making a decision to rely on a module.

See Also

Please enable JavaScript to view the comments powered by Disqus.

Disqus