The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

Releasing a Parrot distribution through PAUSE

In the Parrot distribution, all modules should be owned by the PARROTRE user in PAUSE. This allows a group of maintainers to manage permissions and metadata on the Parrot modules. In the Parrot project, every active a release manager will also be made a member of the PARROTRE group. Current members are: ARANDAL, BDFOY, CHROMATIC, COKE, JESSE, JONATHAN, MDIEP, PARTICLE, PMIC.

Membership in the PARROTRE group isn't required for uploading Parrot distributions to PAUSE. What is required for making a release is that your individual PAUSE ID be granted co-maintainer permissions on all PARROTRE modules. Members of the PARROTRE group have access to grant this permission.

Generally the project manager will add your name to PARROTRE group when you first sign up to take a Parrot release rotation, but it's worth checking with the project manager several weeks ahead of your first release to make sure. (At the moment, the only way to edit the list of members in the group is to write to modules@perl.org and wait for a PAUSE admin to update the list, so it needs to happen well in advance of the release date.)

The PAUSE process

Obtain a personal PAUSE ID

To upload distributions to PAUSE, you need a personal PAUSE login that identifies you as an individual even if you are doing work for a group.

        https://pause.perl.org/pause/authenquery?ACTION=request_id

You'll always upload and interact with PAUSE as your personal ID.

PAUSE mailing lists

PAUSE has a feature to maintain a module as part of a group, which it calls a mailing list. To PAUSE, that just means that the primary contact for the module is a mailing list instead of an individual. Other than that, the "mailing list" term doesn't have much meaning. PAUSE does not offer or maintain mailing lists itself.

Mailing lists have a PAUSE ID, but do not have passwords. Since they do not have passwords, mailing lists cannot upload modules. Mailing list IDs simply provide a focal point for permissions management. Once a mailing list owns the modules for a project, a person who's a member of that group can easily give co-maintainer privileges to anyone else for all modules at the same time. Release managers still upload modules under their own PAUSE ID.

You don't need to be a member of PARROTRE to upload a Parrot distribution. You just need to have co-maintainer permissions on all of the existing modules. If you don't, ask someone listed in PARROTRE.

Join PARROTRE

You only need to be a member of PARROTRE if you need to manage the CPAN permissions for Parrot modules.

There isn't an automated process for joining the PARROTRE mailing list. The project manager will write to modules@perl.org to tell us that you should be added. This isn't an automatic process yet because it has been a very infrequent task. If it becomes a frequent task, that might change.

If you are a member of a PAUSE mailing list, you will have a "Mailinglists menu" section in your PAUSE menu:

        https://pause.perl.org/pause/authenquery?ACTION=select_ml_action
        

If you don't have that, you aren't a member of a mailing list yet. Wait patiently, then ping modules@perl.org to ensure we got the message.

Get co-maintainer permissions on all PARROTRE modules

To upload a distribution that PAUSE will index, you need to have co-maintainer permissions on all of the modules that PAUSE will try to index. Without that, the PAUSE indexer will fail. Additionally, CPAN Search will mark the entire distribution as "Unauthorized".

You'll automatically get first-come permissions on any new modules, and you'll take care of the permissions for those after you upload your distribution.

If you are the PARROTRE permissions manager, use the "Select Mailinglist/Action" link:

       https://pause.perl.org/pause/authenquery?ACTION=select_ml_action

You want to follow the "Change Permissions" action for PARROTRE:

       https://pause.perl.org/pause/authenquery?HIDDENNAME=PARROTRE&ACTIONREQ=share_perms&pause99_select_ml_actio n_sub=Submit
       

The "Change Permissions" form looks the same as the one that you see for your personal PAUSE ID, but now you can edit the permissions for the modules that PARROTRE owns. You'll want to select all of the modules in "Making and unmaking co-maintainers (for both modulelist owners and primary maintainers)" and choose "3.1 Make somebody else co-maintainer".

Uploading the distribution

You cannot upload the distribution as PARROTRE. Ensure that you are a member of PARROTRE, then upload the distribution under your personal PAUSE ID. PAUSE will recognize you as a member of PARROTRE and will treat you as a co-maintainer of all PARROTRE-owned modules.

        https://pause.perl.org/pause/authenquery?ACTION=add_uri
        

Index failures and unauthorized distributions

PAUSE allows you to upload any module you like, even if someone else owns it. However, the PAUSE indexer will not index modules that you don't have permissions to upload.

Apart from that, CPAN Search (search.cpan.org) does its own checks, and if your PAUSE ID doesn't have permissions for one of the modules in the distribution, CPAN Search marks the entire distribution as "Unauthorized". This is effectively the same as the PAUSE indexer not indexing the module, but it's actually a separate and unconnected process.

If the indexer finds unauthorized modules, it means the modules are either Parrot modules with the wrong owner set, or they're external modules that need to be skipped by the indexer.

If the module is part of the Parrot distribution (these are generally named Parrot::*), look it up in PAUSE under "View Permissions". The "owner" should be PARROTRE. If the owner is some other user, contact that user and ask them to assign ownership to PARROTRE.

Once you fix the permissions, you can ask PAUSE to re-index the module:

       https://pause.perl.org/pause/authenquery?ACTION=reindex

If the module is an external module and just copied into the distribution (e.g. lib/Test/More.pm), then it shouldn't be indexed by PAUSE at all. Modify META.yml and add the directory, file, or package name to the list of modules under 'no_index'.

Unfortunately, at this time there is no way to update the META.yml file on a distribution that has already been uploaded to CPAN, and no way to test the META.yml file against CPAN before uploading the distribution.

Including a new module in the Parrot distribution

If you're the Parrot release manager and there are new modules in the distribution, upload the distribution normally under your own ID.

PAUSE will detect the new modules and give your personal ID first-come ownership of the modules. It's your job to transfer primary ownership of those modules to PARROTRE. This does not affect the distribution you just uploaded, but it allows the other release managers to maintain them. (You do this step after you upload the distribution and after PAUSE indexes it.)

To transfer permissions, go to the "Change Permissions" page in PAUSE and select the new modules in "2. You are primary maintainer". You can select multiple modules at the same time. Once selected, choose "2.1 Pass primary maintainership status to somebody else (giving it up at the same time)". In the next form page, pass the primary maintainership to PARROTRE.

        https://pause.perl.org/pause/authenquery?ACTION=share_perms
        

Checking the distribution

Once PAUSE indexes the distribution, it will send you a report if it encounters any errors. If you don't have the correct permissions for any of the modules in the distribution, PAUSE will send you the indexer's report that shows the problem. Fix the permissions on the modules PAUSE complains about. If you need help, contact the other release managers, and if they don't have the answer, write to modules@perl.org.

Author

The original version of this guide was written by brian d foy <bdfoy@cpan.org>, and you can modify and distribute in under the same terms as Parrot.