NEILB's Blog

This is the first part of a series about what happens when you upload a release to CPAN, via PAUSE. I started writing it as a single post, but it became way too long before I was even half way. This post will try to be the executive summary, or Reader's Digest condensed version if you like. Subsequent posts will dive into the details; I'll be filling gaps in my knowledge as I go, and expecting to be corrected on plenty of points as well.

The following illustrates the main steps in the upload process, the third being the most hairy:

Here are the highlights:

• You upload your dist, perhaps using cpan-upload.
• PAUSE checks whether the file's been seen before, and fails with a 409 status code if it has. You can't upload a 'fixed copy' of a release, you have to bump the version.
• PAUSE puts the file in your author directory. My PAUSE id is NEILB, so my author directory is authors/id/N/NE/NEILB.
• You receive the first of possibly two emails from PAUSE, telling you whether everything was ok to this point. Is there any way it can fail?
• The file is now "on CPAN", as your directory is mirrored across the hundreds of CPAN mirrors, and it will end up on BackPAN (my directory on BackPAN).
• If it's a developer release, it goes no further (so you only get one email).
• PAUSE checks each package in your release to see if you're allowed to release it. You must either be the owner or have co-maint (see the doc for PAUSE::Permissions). If you've flagged the package with no_index in the metadata, then the check is skipped.
• You are given ownership ('f' permission) for any packages that don't currently have any permission associated with them in PAUSE.
• The second email is sent to you, with the results of the permissions check.
• If none of the packages failed, then your release is 'indexed', which I think means a number of things, but the main one being that it will appear in 02packages.details.txt. This is the index of "what packages are on CPAN right now". My module PAUSE::Packages gives an interface to this file; there are at least five other modules that do as well, which are listed in the SEE ALSO section.

I'm writing up this much because I want to discuss it at the QA Hackathon this week. In particular I think the permissions check should be separate from, and earlier than, the indexing stage. This would mean that developer releases would still be permissions checked and would give you ownership. Packages with no_index would also still be permission-checked.

Even further though, I think the permissions check should be a precondition to putting a release in the author's directory. I know plenty of more experienced people than me disagree on the second point, but am looking forward to a good discussion and hopefully some illumination at least.

Post-hackathon

We had a good discussion around the first point, and PAUSE is going to be changing. Hopefully DAGOLDEN will be writing a summary of all the PAUSE-related decisions.

As I knew going in, checking permissions on upload was a non-starter. That's ok, I'm happy to bide my time :-)