PAUSE

The Perl Authors Upload Server

Last modified: Mon Dec 13 09:28:36 CET 1999 $Revision: 1.51 $

This document informs about

Uploading
Registering as a developer
Visit PAUSE
Your duties, the basics, traps
Register your namespace!
Other conventions you should know about
Related services on PAUSE
SSL support on PAUSE
Software used to run PAUSE

Uploading

A server dedicated to collect the work of perl authors is a Perl Authors Upload Server (PAUSE). PAUSE provides personal directories and enables their owners to upload their work into that directory themselves. The procedure of uploading is trivial and needs no explanation here. You'll understand it as soon as you have access to the PAUSE. There's only one thing you need to know as soon as possible:

Please, 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 und code: /(README|readme|\.html|\.txt)$/. Filenames matching this RE 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, so they can be installed in a standard way.

The upload server is not very well connected. Please don't mirror from there. The funet server in Finland mirrors every hour the new incoming stuff, so please try to download from there or from other CPAN sites.

Register yourself

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, if you have some porting material or patches you would like to contribute to the archive, send the following to the maintainers at modules@perl.org

your name
your email address
your homepage if you have one
your preferred user-ID on CPAN. It must be between 4 and 9 characters long, all uppercase, letters only. One dash allowed.
a description of what you're planning to contribute
for modules a description in module list format (DSLI entry, which is: Development stage, Support level, Language used, Interface style (see the modulelist), and a 44 character description).
for scripts, ports, documentation, etc. please send a concise description that helps us to categorize the issue so we can forward your mail to the maintainers of the corresponding archive branch.
It would be very nice, if you could also send a note about where you have discussed some or all parts of your contribution publicly, and if there was at least a little bit of interest. We are quite open for submissions, but we owe our users at least some rudimentary quality control. If your work has never been discussed publicly, then it's extremely difficult for us to make our judgement whether to accept the submission or not.

Also: think carefully and honestly whether your module would be better off if it were integrated as an option 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.

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. All mails to modules@perl.org is archived at http://www.xray.mpe.mpg.de/mailing-lists/modules. modules@perl.org isn't a mailing list, just an alias for the front desk of the Perl 5 modules list. Please do not subscribe. Visit the archive instead. Thanks!

Visit PAUSE

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.kbx.de/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.

Your duties, the basics, traps

We trust that you have read the module list top down and bottom up and back again 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)):

Think, better even talk before you upload
Respect the namespace of others

Register your namespace!

Please, talk to modules@perl.org before you decide upon the namespace you're going to use for your module. Usually it's not considered the perl way to have beaurocratic conventions, but when it comes to namespace pollution, there is the need of coordination. Just like the InterNIC has to care for unique names for internet hosts, somebody has to (sort of) guarantee uniqueness, consistency, and sanity of module names. The modulelist is the place where all currently registered module names can be found and the email address modules@perl.org is an alias for a hand full of experienced volunteers who maintain the module list and give advice for the appropriate namespace for your modules.

Please consider the namespace you're going to occupy with all due sensitivity. Discuss it in the appropriate fora. Read what the modulelist has to say about this. Please pay special attention to the hints about 'cutesy' names. Reading these sections carefully will help you and us to greatly improve the usefulness of the CPAN and avoid cumbersome renaming at a later date.

The indexes that are maintained automatically on CPAN all double check if the module names that are used in the uploaded packages are registered. The indexer unwraps all packages and scans the source code for package declarations. You run the risk of being ignored by the index generator if you do not talk to the modulelist maintainers about the namespace you are using.

modules@perl.org is not a mailing list. Please do not try to subscribe. We do not want to establish yet another perl mailing list. If we encounter hot topics, we move the discussion to the appropriate mailing lists. The traffic on modules@perl.org is archived at http://www.xray.mpe.mpg.de/mailing-lists/modules/.

Other conventions you should know about

Do not upload the READMEs that are integrated in your distribution files. PAUSE is designed to take care of unwrappig 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)' filename

on the filenames in question. The CPAN indexer will run this code within a Safe compartement.

The automatic integration of your work into several indexes and directory trees is not always in accordance with what you desire. If you want to prevent propagation to places outside of your directory, simply choose a filename that matches /\d\.\d+_\d/, i.e. something that looks like derived from a perl subversion number (maybe because it is a perl subversion). PAUSE will leave such distributions untouched: no readme will be extracted, no index will be updated, no symlinks will be created.

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 cpan-testers. 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.

Related services on PAUSE

The interdependence between metadata generators, metadata files, database tables, and human intervention are as follows:

Modulelist Maintainance
The above described Module List is the heart. It is maintained manually and all modules listed there have to go through the standard approval procedure.

On a more or less regular basis, the Module List is published on USENET in the newsgroups comp.lang.perl.modules, comp.answers, and news.answers. Simultaneously an HTML version and a machine readable representation are uploaded to CPAN. Jon Orwant is on the board of the module list maintainance group. He's maintaining a document with a different, considerably more verbose view on the evolving modules scene, CPAN.html.

Authors Registration
The maintainers of the Module List do not only register modules' namespaces, they also register new authors and assign them a password that enables them to upload to the CPAN.

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.

Upload Scanner
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 devides the modules by the chapters of the Module List: by-category.

SSL support on PAUSE

PAUSE supports both http and https (SSL). Please try PAUSE over an SSL connection if you can. For our firewall impaired developers we will keep up the http server for the time being. So if you have difficulties accessing https, you can always fall back to http, but using SSL greatly improves your and PAUSE's security.

PAUSE's private key is not registered with any certificate authority, so when you access the SSL channel for the first time, your browser will most likely complain that it does not recognize the authority who signed its Certificate. You can safely ignore this error. When you verify the fingerprint to be B4:96:CD:65:5C:B4:2F:2A:EC:D6:5E:5F:FC:D0:8E:0B, then you know you're talking to the real PAUSE.

Software

The software running PAUSE consists of a database, which is driven by mysql and a mod_perl server with SSL. Besides many of the perl standard modules like CGI, Data::Dumper, Text::Wrap, File, Directory, and IO modules, PAUSE itself uses lots of modules from the CPAN. For a complete list, feel free to visit http://pause.kbx.de/perl-status. Also a lot of work is done by the mirror program by Lee McLoughlin, available from the CPAN scripts/ftpstuff directory.

Thanks to all of you for your great contributions!

Contact Andreas König for any questions.

PGP public key for Andreas Koenig <koenig@franz.ww.TU-Berlin.DE>
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2i
Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface

mQCNAy/cHRcAAAEEANwnl+iKMmChV2bclGabDurm29HHOSSc6cB3jDLC0AzOHeai
KpWaht05TCh95Bdx19YcfCm+NEd3FK0O1dcitufpNR7QJUvYVuN1AscLoYBmU8BW
ioIPsdjAj3IVdjwhS5loTyjoIT2/OWC2FxCUV5rSyAo/mQQ9knx7PGaUl9ctAAUT
tC1BbmRyZWFzIEtvZW5pZyA8a29lbmlnQGZyYW56Lnd3LlRVLUJlcmxpbi5ERT6J
AJUCBRAwcO+wYOb8KOlZZVUBAVB1BAC1B/zPYWODvdOfEdLtdtqhR/H9ULyaVmOM
rS1TNpDdnQzzx8jzufHPJbWaY1XbOl3XYJy59lGUGN6rYKj91sDgvSmEL1ojHWmP
+Ox/FU9ZuNVvwz+qYbw031JLDKX6JWyby6kr742SDX/2Cw99knzh3VpdCUwZYjAq
DZDrUwUx+4kAlQMFEDBw/xB8ezxmlJfXLQEBpcED/0vP1gyeKTGZGZTg94OzdWlg
1fRjoVIXqwc10Fce6HnodJ5ScTiVaspA/ppq0p0eKoArPmGxy6ZjX3urr4PtdRck
5HWf0p8K1pBJ65P7x+vOlN3/v9L9kxtUjHxn/4U0X+xAhOlYQuz3FIdnGz7EDnaK
6z2ss1hdSC1mTrAF4JME
=zlTu
-----END PGP PUBLIC KEY BLOCK-----

Modulelist Maintainance The above described Module List is the heart. It is maintained manually and all modules listed there have to go through the standard approval procedure.
On a more or less regular basis, the Module List is published on USENET in the newsgroups comp.lang.perl.modules, comp.answers, and news.answers. Simultaneously an HTML version and a machine readable representation are uploaded to CPAN.		Jon Orwant is on the board of the module list maintainance group. He's maintaining a document with a different, considerably more verbose view on the evolving modules scene, CPAN.html.
Authors Registration The maintainers of the Module List do not only register modules' namespaces, they also register new authors and assign them a password that enables them to upload to the CPAN.
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.
Upload Scanner 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 devides the modules by the chapters of the Module List: by-category.