From c4d5526069db43c1ca6bc5dfd72138cfcedc102e Mon Sep 17 00:00:00 2001 From: fukachan Date: Sun, 25 Mar 2001 12:46:51 +0000 Subject: informational --- doc/devel/memo/04pause.html | 408 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 doc/devel/memo/04pause.html (limited to 'doc') diff --git a/doc/devel/memo/04pause.html b/doc/devel/memo/04pause.html new file mode 100644 index 00000000..0f726786 --- /dev/null +++ b/doc/devel/memo/04pause.html @@ -0,0 +1,408 @@ + + +PAUSE +

The Perl Authors Upload Server

+

+ +Last modified: Tue Dec 5 21:07:00 CET 2000 + +$Revision$ +

+ +

Contents

+ +

This document informs about

+
    +
  1. Status of this document
    2. +
  2. Uploading
    3. +
  3. Registering as a developer
    4. +
  4. Visit PAUSE
    5. +
  5. Your duties, the basics, traps
    6. +
  6. Register your namespace!
    7. +
  7. Other conventions you should know about
    8. +
  8. Related services on PAUSE
    9. +
  9. SSL support on PAUSE
    10. +
  10. Software used to run PAUSE
    11. +
+ +

Status of this document

+ +This document is mirrored on CPAN as CPAN/modules/04pause.html. + +

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 +(Note: your email will be made publicly available) + + + +
+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.

+ +

And please do consult these archive 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. 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. Note by KS: If you want +a quick response, be sure to ask if anybody actually reads the list. +This is guaranteed to produce at least ten responses in rapid +suggestion (none of which will respond to your proposal).

+ + +

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)): + +
    +
  1. Think, better even talk before you upload
    2. +
  2. Respect the namespace of others
    3. +
+ +

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 +(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.

+ +

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

+ +

Please consult these archives 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. 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.

+ + +

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-----
+
+ + -- cgit v1.2.1