$Id: 04pause.html 596 2005-04-19 06:17:44Z k $
This document informs about
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.
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, 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.xray.mpe.mpg.de/mailing-lists/modules. modules@perl.org isn't a mailing list, just an alias for the maintainers of the Perl 5 modules list. 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.
Please, talk to other people (comp.lang.perl.modules, modules@perl.org or any mailing list that fits your problem domain) 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--time permitting--try to 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. 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.
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, maybe you can help the users of your module better by giving them an overview about similar modules.
And please do consult the archives of modules@perl.org before you post a module proposal. The fulltext search capabilities of the archive should help you to find similar suggestions and contact addresses. modules@perl.org is low volume, so your search in the archive is quite targetted. 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/. The module list maintainers themselves are mostly lurkers. You need not wait for a response. Generally a lack of response can be taken as acceptance of the module name being proposed.
When you're done with all your preparations, considerations, and investigations, visit the PAUSE and fill in the form for a new module namespace. Take your time filling in the rationale of the module proposal. Consider, your form will be posted to modules@perl.org too, so other developers will probably stumble over this description many years later. The better the decription, the better the chances that your module will actually be used.
You need not wait for approval. You can upload anytime, even before you fill in the form. Uploading and registering are only loosely coupled.
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
(namely all *.pm
files) 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.
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 compartement, 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.
The automatic integration of your work into several indexes
and directory trees is not always what you desire. If you want to
prevent propagation to places outside of your directory, simply
choose a filename that matches /\d\.\d+_\d/
. PAUSE
will leave such distributions alone: 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.
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.
The interdependence between metadata generators, metadata files, database tables, and human intervention are as follows:
Modulelist MaintainanceThe 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 in HTML and TXT format 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 RegistrationThe 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 ScannerWhen 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. |
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 ignore this caveat.
The fingerprint of the self-signed certificate that expires on
2009-01-07 is
MD5 Fingerprint=83:E9:A6:4C:EC:CC:60:A8:A1:6C:5F:30:11:53:41:06
The software running PAUSE consists of a database, which is driven by mysql and a mod_perl server with Ben-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 https://pause.perl.org/perl-status. Also a lot of work is done by the mirror program by Lee McLoughlin, available from the CPAN scripts/ftpstuff directory.
The PAUSE source code is kept in a subversion repository at http://pause.perl.org:5459/svn/pause/trunk.
If you do not have a subversion client, a tarball of the repository is
produced by a cronjob and accessible in the directory ftp://pause.perl.org/pub/PAUSE/PAUSE-code/.
The filenames of the snapshots in that directory match
/^pause-wc-(\d+)\.tar\.gz$/
where $1
is the
revision number of the repository.
Thanks to all of you for your great contributions!
GnuPG public key for Andreas Koenig <andreas.koenig@anima.de> -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v1.2.5 (GNU/Linux) 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 =7nAs -----END PGP PUBLIC KEY BLOCK-----