This document is mirrored on CPAN as CPAN/modules/04pause.html.
A server dedicated to collect the work of perl authors is a [Perl programming] Authors Upload Server (PAUSE). PAUSE provides personal directories and enables their owners to upload their work into that directory themselves.
Important: make sure the filename you choose contains a version
number. For security reasons you will never be able to upload a
file with identical name again. This strict requirement does have one
exception: documentation files may be overwritten. There's a simple
regular expression that draws the line between docu and code:
/(readme|\.html|\.txt|\.[xy]ml|\.json|\.[pr]df|\.pod)(\.gz|\.bz2)?$/i. Filenames matching this
regexp can be uploaded as often as you like. By the way: it is highly
appreciated if your packages come tarred and gzipped with a
Makefile.PL (or Build.PL), so they can be installed in a standard way.
Use one of the many CPAN Mirrors to download from.
Registered developers have a unique username and a home directory in the authors/id/ tree of CPAN. The write access to that directory is password protected.
If you have written a module, script, or documentation you would like to contribute to the archive, visit pause.perl.org Registration (Non-SSL version) and fill in the form. You will be notified by email about your registration. Please allow three weeks for proceeding, which should be the maximum during vacation time. Normally we hope to register you within a week. The resulting email traffic will run through modules@perl.org and will be archived at http://www.nntp.perl.org/group/perl.modules/. modules@perl.org isn't a mailing list, just an alias for the maintainers of the Perl 5 modules database. Please do not try to subscribe. Visit the archive instead.
As soon as you have a password (see registering) you are enabled to use some forms to interact with the PAUSE database (Non-SSL version). You can add files to your home directory, edit your name, email, and homepage address, delete your files, change your password on PAUSE, etc.
If you haven't got a password yet or have forgotten it, please visit https://pause.perl.org/pause/query?ACTION=mailpw (Non-SSL version) for further instructions.
Please, whenever you exchange email with the maintainers of PAUSE, mention either your userid or the name you used when you registered.
perlmodinstall,
perlmodlib, perlmodstyle, and
perlnewmod manpages and that you regularly check out
uploads to CPAN and that you have been watching CPAN activities for a
while to have an impression of how things fit together. It usually
boils down to (slogan shamelessly stolen and adapted from sudo(1)):
Before uploading a new module to CPAN, please carefully consider:
Choosing a good name is important if you want people to find your module on CPAN and understand (from the name alone) what it does.
Likewise, there are so many modules already on CPAN that it's a good idea to be sure that your module is doing something new or at least different (and hopefully better) than something already on CPAN. Search for similar modules on metacpan.org or search.cpan.org.
If you have never uploaded a module to CPAN before (and even if you have), you are strongly encouraged to get feedback on PrePAN.
PrePAN is a site dedicated to discussing ideas for CPAN modules with other Perl developers and is a great resource for new (and experienced) Perl developers. You can also consider discussing your ideas in other local community groups or online community sites like Perl Monks.
Also: think carefully and honestly whether your module would be better off if it were integrated into an already existing module. Sometimes it is for the best to put aside personal glory and join a collaborative effort: Perl itself is a good example of this. Contact the author of an existing module and ask whether your new features would fit into his framework. Even if you in the end decide to release the module as your very own, you really should know your 'competition', that is, know all the similar modules and the features they offer. Maybe you can learn from them, maybe you can help the users of your module better by giving them an overview about similar modules.
Authors upload new modules to PAUSE, which is responsible for inspecting,
validating and indexing uploads. PAUSE unwraps the upload and scans the source code
(namely all *.pm files) for package declarations. In order for
a module to be indexed, the submitting author must be the owner or an authorized
maintainer for every package namespace found (unless the namespace is new, in
which case the uploading author becomes the owner of it).
After a module is uploaded to PAUSE, it propagates to www.cpan.org and dozens of other CPAN mirrors around the world. PAUSE also creates a number of index files used by CPAN clients like CPAN(.pm), CPANPLUS and cpanminus:
authors/00whois.html authors/00whois.xml authors/01mailrc.txt.gz modules/02packages.details.txt.gz modules/03modlist.data.gz modules/06perms.txt.gz
In the spirit of security by visibility, PAUSE sends an immediate email to your secret email address about the upload and, if your upload is a regular (not developer) module distribution, a few minutes later an email about the indexing process.
CPAN search engines like metacpan.org and search.cpan.org use these indexes and other heuristics to allow Perl developers to find modules that interest them.
If you have questions about these, be sure to send them to the right place:
So there's a module on CPAN that has a critical bug, lacks some features, or is generally under-maintained and you would like to step in?
It's great that you want to help out and we, the PAUSE admins, really don't want to create any unnecessary barrier to getting involved with an existing module (or distribution) on CPAN. There are, however, some precautions we have to take. The following paragraphs outline the reason for these precautions and the steps you have to take. Please read them carefully.
The majority of modules on CPAN has active maintainers. If the maintainer didn't answer the ticket you created in the request tracker, maybe she doesn't know about the CPAN ticketing system yet? Or she's just very busy this week and will get back to you in due time. The best way of helping out is to talk to the current maintainer about what you can do. Getting the PAUSE admins involved is only a last resort!
In some circumstances, we can grant co-maintenance permissions to you or others if the current maintainer of a module has entirely disappeared. You have to understand that is not a decision we make lightly. We are essentially giving write access to somebody else's work to third parties without explicit consent from the missing author. Since almost all code on CPAN has a free license, this is likely unproblematic from a legal point of view, but any violation of a contributor's trust in the PAUSE/CPAN mechanisms is a serious blow against the work of everybody who contributes to CPAN. For this reason, we try to tread very lightly, make the least possible use of the administrative privileges and attempt to protect voluntary contributors like yourself or the author of the module at hand from any unnecessary burden.
You have to realize that the author has probably invested a signficiant amount of time into writing the code in the first place and then gone through the additional work of making it available to others via CPAN free of charge. Therefore, it is crucial to be very polite when asking him or her for co-maintenance permissions. Politeness, however, does not suffice. Particularly when maintaining a module for which you received co-maintenance permissions from the admins (as opposed to being appointed by the author himself), you are *required* to respect the work and design of the author. A common fallacy is that people think they are much better programmers than their predecessors and that entitles them to judge others code quality and refactor everything. Whether or not your style is "better" is entirely irrelevant as it is not your code. Do not be arrogant, be respectful and tread lightly!
If you published your code to CPAN, then went on a hiking vacation (or to hospital) for a couple of weeks only to see that somebody took over, completely changed the design, and generally wreaked havoc, you would probably be rightfully upset and lose the good will that made you contribute in the first place. In order to prevent from happening, please go through the following steps and remember to be respectful all along:
Usually, after all this hassle, we are reasonably quick at assigning co-maintenance permissions, but don't hold your breath, we're only human after all. Most requests won't even get here as many authors who moved on and don't maintain their modules any more are very happy to see them taken care of and will assign (primary or) co-maintenance permissions after you've tracked them down and asked nicely.
Good luck and thanks for stepping up.
Other people can always upload modules with the same name as the module you uploaded but PAUSE will only index the modules that primary maintainer, or one of the designated co-maintainers have uploaded. If you were the first to upload a module, you automatically became the primary maintainer.
If you would like to allow other people to upload official versions of a certain module you can give them co-maintainer status. You do that using the followng steps:
Remember, you can set several people as co-maintainers, and as long as you don't give up your Primary maintainer status you can always revoke the co-maintainer rights of anyone by selecting the 3.2 button.
If you want to give up control of one of your modules you can set another PAUSE user to become the Primary maintainer of a module of yours. After doing this the other person will have the right to add/remove co-maintainers and to change who is the primary maintainer.
In order to do this you have to follow the following steps:
Do not upload the READMEs that are integrated in your distribution
files. PAUSE is designed to take care of unwrapping your file with tar
or zip, registering all the modules it finds in there, and placing the
readme file (i.e. a file with the name README in
the top level directory of your package) into your directory. PAUSE
will change the name of the file to
package-name.readme. It should do so within
a few hours after your upload.
Please make sure all your *.pm files contain a
$VERSION variable that conforms to the CPAN rules, i.e.
the complete computation of $VERSION must take place on the one first
line within the module that assigns to it. You can test if this is the
case by running
perl -MExtUtils::MakeMaker -le
'print MM->parse_version(shift)' 'file'on the filenames in question. The CPAN indexer will run this code within a Safe compartment, so maybe even if the above command succeeds, PAUSE may fail if you're doing file IO or other potentially dangerous things within that line.
Before you decide which style of versioning you prefer, you might want to read the version manpage.
The automatic integration of your work into several indexes and directory trees is not always what you desire. Often you want to release code for testing out the next release. Code that propagates through CPAN but is not in a stable state. Something between two versions.
If you want to do that simply choose a filename that matches
/\d\.\d+_\d/ or contains TRIAL.
Please choose a sequence that is easy to comprehend. People have adopted
different conventions:
# 1.92 release and bug fixes 1.92 1.9201 1.9202 ... # dev releases towards 1.93 1.92_50 1.92_51 1.92_52 ...
This allows two separate development tracks between 1.92 and 1.93.
Other people do odd and even, with all odd majors always being dev releases:
0.15_01 0.15_02 0.16 0.1601 0.1602 0.17_01 0.17_02 ...
PAUSE will leave the underscore distributions alone: no readme will be extracted, no index will be updated, no symlinks will be created. Of course many users on the CPAN will take note of the developer releases. Cpan testers will test them and bug chasers will probably file bug reports in RT.
Any distribution that arrives at PAUSE is checked for package names contained in the distribution. A package name that arrives for the first time is automatically assigned either to the author who submitted it or to user perl if the distribution file is a perl distribution. A package name that has already been used before must be submitted by its author, otherwise PAUSE will trigger a warning to the administrator. That way PAUSE will prevent accidental usage of a package namespace by more than one author.
Be prepared that very soon after your upload your module will be tested on dozens of architectures by the never tired cpantesters. This helpful lot will send their findings to their mailing list and collect the results in a database. If they find problems, they try to diagnose or even solve them and inform you about their findings. So be prepared to get mail from them before you have closed the buffer in your editor.
Module::Build is an effort to overcome many deficiencies in
MakeMaker and CPAN. One idea in that context is the storage of
module-metadata in a file META.yml,
that is being integrated into the module-tarball. PAUSE is supposed
to follow this emerging standard. The current code base of the PAUSE
indexer supports META.yml by extracting it and storing it in a
separate file that is called
package-name.meta in the same directory.
The PAUSE indexer honours the contents of the no_index and
the provides fields. All other fields are currently ignored.
Two documents are available about authors. 00whois.html is a list of authors, mailing lists and mailing list archives in HTML format,
And 01mailrc.txt.gz is a smaller list intended to be used as a .mailrc file. Both files are maintained automatically.
When new files arrive on the PAUSE, an Upload Scanner program scans the new files and categorizes them according to their contents. It tries to detect namespace clashes and to keep track of version numbers.
The document 01modules.index.html lists only the most recent distribution files that contain the latest of any given module that is available on CPAN. A second version of this document is also available that is sorted by modification date. Both are maintained by the scanner automatically.
The listing 02packages.details.txt is also produced automatically. It is intended for programs but sometimes is a valuable information for humans too. It simply lists the current version number and the distribution file for all packages found on CPAN.
There are also two symlink trees of modules maintained automatically. One is based on the basenames of the packages involved: by-module and the other one divides the modules by the chapters of the Module List: by-category.
You have forgotten how you're supposed to package your software? Maybe the perlnewmod manpage can help you.
A real FAQ is about how to adopt or take over a module from somebody else? perlfaq7 has the full answer (as of rev. 393).
You wanted to ask questions about authoring? Maybe the module authors mailinglist or the Perl Monks will give you a lead.
You wanted to include proper tests in your package? A myriad of general purpose and custom tailored testing modules are discussed on the QA mailing list.
The PAUSE source code is kept in a git repository at git://github.com/andk/pause.git view it at https://github.com/andk/pause.
Please file bug reports against software running on PAUSE to the github tracker. Bug report with security implication are best sent to pause-admin@perl.org.
Thanks to all of you for your great contributions!
GnuPG public key for Andreas Koenig <andreas.koenig.7os6VVqR@franz.ak.mind.de> -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v1.4.6 (GNU/Linux) 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 =HPT0 -----END PGP PUBLIC KEY BLOCK-----