=pod

=head1 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.)

=head1 The PAUSE process

=head2 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.

=head2 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.

=head2 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.

=head2 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".

=head2 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
	
=head2 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.


=head2 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
	
=head2 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.

=head1 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.
	
=cut