FAQ! Read this first!

This is the monthly posting of the FAQ for the perl5-porters mailing
list, the central mailing list for the development of the perl
interpreter.

-----------------------------------------------------------------------
Contents

1) Administration
2) Questions about perl5-porters itself
3) Development questions
4) Who's Who

-----------------------------------------------------------------------
1) Administration

1.1) Help! How do I unsubscribe?

Send mail to <perl5-porters-unsubscribe@perl.org>, and await a response.
Once you reply to the response, you'll be unsubscribed.

If that doesn't work, find your subscription address - it'll be in the
Return-Path header of any mails from p5p to you. If that's
God@heaven.af.mil, send mail to
<perl5-porters-unsubscribe-God=heaven.af.mil@perl.org>.

1.2) I'm not subscribed - how do I subscribe?

Send mail to <perl5-porters-subscribe@perl.org>.
To specify God@heaven.af.mil as your subscription address, send mail
to <perl5-porters-subscribe-God=heaven.af.mil@perl.org>.

1.3) How do I retrieve old messages?

Every message you get from perl5-porters will have an autogenerated
From line. For instance:
<perl5-porters-5523-God=heaven.af.mil@perl.org>

The number in the middle, 5523, is the sequence number. To get the
message with a particular sequence number mailed to you, send mail to
<perl5-porters-get.5523@perl.org>.

To retrieve a range of messages mailed to you in a digest, for instance,
the messages with sequence numbers from 4902 to 4950, send mail to
<perl5-porters-get.4902-4950@perl.org>. You may request a maximum of
100 messages in a single digest.

1.4) Is there a web archive?

Yes, there is, and it's at
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/

1.5) perl5-porters is too big! Is there a digest?

Funny you should mention that. Simon Cozens compiles a weekly
summary of the highlights, with links to the archive where more
extensive reading is recommended. These can be found at
http://www.perl.com/pub/q/archivep5p

If you want to receive all the messages, but batched into a single mail
per day, you can subscribe to <perl5-porters-digest@perl.org> instead;
send mail to <perl5-porters-digest-subscribe@perl.org>. Be warned that
replying to messages from the digest will mess up threading on
things like the web archive - at least set your outgoing Subject header
to the subject of the individual message you're replying to.

1.6) How do I get this document?

Uh, you're reading it, aren't you? Oh well, life is strange. Send
mail to <perl5-porters-faq@perl.org> and you'll receive a copy.

1.7) How do I submit/suggest questions for this FAQ?

Send mail to <p5p-faq@perlhacker.org>. This will reach the FAQ
maintainer who is currently Simon Cozens.

The FAQ was last updated Sat Jun 16 2001


-----------------------------------------------------------------------
2) Questions about perl5-porters itself

2.1) What is perl5-porters for?

perl5-porters is, briefly, for all topics related to the development of
the Perl language and the perl interpreter. It's for reporting and
fixing bugs, working towards the next version of perl, and improving the
quality of the Perl language.

2.2) What is perl5-porters not for?

    * Questions about programming Perl.
    * Questions covered in the Perl FAQ.
    * Questions about programming Perl.
    * Spam.
    * Questions about programming Perl.

2.3) Are there any rules?

No. However, the list is refereed, primarily in order to prevent
empassioned debate degenerating into flame war. The refereeing system is
explained below.

Larry's advice from perlstyle applies just as well here as it does to Perl
programming:

    * Be consistent.
    * Be nice.

The established medium for messages is plain text. If your email client
wants to send things in HTML, please try and discipline it.

2.4) What is the refereeing system?

Sarathy explains:

    * There will be a panel of referees.
    * The panel monitors both threads and personalities.
    * Messages from subscribers normally go through immediately.
    * Messages from non-subscribers are normally subject to moderation,
      except perhaps messages sent via perlbug.  (This is meant to catch
      spam and usage questions.)
    * Referees normally work behind-the-scenes.  They will privately
      remind people to avoid flogging dead equines, provocative
      language, off-topic conversations etc.
    * A simple majority among the referees can choose to moderate/unmoderate
      threads/personalities.  (The moderation state is sticky--once enabled,
      it stays that way, until it is disabled.)
    * Moderated messages are only posted after approval by the referees.
      If not approved, they are dropped with a polite notification to
      sender on the reason(s).

And note we say "referees", not "moderators". This is a deliberate comment
on their role - Sarathy again:

    Referees aren't there to impede or even regulate the play--they're
    there to ensure smooth conduct of it.  Benching a player would be
    the last resort.

    The way I see it, a referee is just a voice of reason with some
    recognized authority, so that they may put their foot down if it
    comes down to it. (That shouldn't happen until things get ugly,
    which I hope they seldom do.)

For a list of the current referees, see question 4.2

2.5) Some idiot didn't read question 2.2, and has just posted a program
to the list and asked where the bug is. What's the best way to flame
them?

Peter Prymmer did it rather well:

Perhaps subscribing to the beginners mailing list by sending a message
to beginners-subscribe@perl.org could help you. Try also pointing a
web browser at the following URLs:

   http://lists.perl.org/showlist.cgi?name=beginners
   http://lists.perl.org/
   http://www.perlmonks.org/

Good luck.

There's also a separate beginners-cgi mailing list for trivial CGI 
questions. Simply make the obvious substitutions to the above.

-----------------------------------------------------------------------
3) Development questions

3.1) How do I report a bug?

First, are you sure it's a bug in Perl itself, not just a bug in your
code? Take the problem out of the context of your current program and
write a short test program to reproduce it - as short as you possibly
can. It's far easily to clearly detect a Perl bug if it's demonstrated
in 5 lines of code, rather than buried somewhere in the middle of a
500-line program.

Next, do we already know about it? Check with the bug ticketing system
at http://bugs.perl.org/

It's always worth getting someone else to look it over and confirm that
this really is a Perl bug, not just a thinko. If there's nobody around
to do that, consider asking on the comp.lang.perl.misc or
comp.lang.perl.moderated newsgroups.

Now, if you've really got a bug, type "perlbug" at your prompt, and
follow the instructions. It really helps us if you provide: your
demonstration code, what you got, what you think you should have got,
and the relevant part of the Perl documentation that makes you think
that.

3.2) I want to get involved! What can I do?

Follow the list for a few weeks or months to get an idea of what goes
on, and see if anything pops up that you're interested in. Occasionally
someone will request a fix, and that's your chance!

If there doesn't appear to be anything you want to or are able to do,
have a look in your Perl source kit: you'll find the files Todo and
Todo-5.6 - some of the items there are being worked on, so check
back-issues of p5p. Furthermore, you don't need to be an expert
programmer: *anyone* can help with proof-reading, correcting and
expanding the documentation, for instance. There's certainly a place
for anyone who truly wants to get involved, and over time, you'll find
it.

You should also read perlhack.pod, Porting/pumpkin.pod and
Porting/patching.pod - these will tell you how to create and submit
patches, as well as some more philosophical issues involved in patching
Perl. To summarise:

    * diff -ruN perl-current perl-patched > patch and append that
      verbatim, preferably not as an attachment, to your post.
    * Drastic changes to the syntax and/or operation of Perl are
      going to be viewed with a lot of suspicion. Start small.
    * Patches speak louder than words. Having ideas is good, but
      taking the time to implement them will improve their credibility.
    * At least one person will think your patch sucks. It's better to
      let the code stand on its own merits than to get into arguments.

3.3) I've created a patch, but I'd like someone to check it over
before I post it to the list. What should I do?

The first thing you should do is relax! We don't bite, and we appreciate
people who want to help. Just go for it. However, if you're still
worried about whether you should send the patch, email the relevant
pumpking for the area you're patching, or one of the referees.

3.4) Is Perl in CVS?

Perl isn't available by anonymous CVS. Perl is, however, kept under
development control - it's using a Perforce server which is currently
hosted for us at ActiveState. Some pumpkings have write access to this
server. There is no public read access to this server - see 3.6 below.

3.5) What is the APC?

When a change is made on the Perforce server, a patch is generated and
placed in the Archive of Perl Changes. This is located at
ftp://ftp.linux.activestate.com/pub/staff/gsar/APC/

The directory diffs/ contains patches against the latest release.

3.6) What is perl-current?

There's also a directory called "perl-current" in the APC, which
contains the very latest Perforce snapshot of Perl. This is the closest
it gets to an anonymous CVS, and this snapshot is what, ideally, you
should patch against.

Since downloading the whole thing from FTP is wasteful, you can either
keep yourself up-to-date using the diffs as mentioned above, or you can
use rsync - the following command will update the directory "bleadperl"
on your computer to match perl-current:

rsync -auvz rsync://ftp.linux.activestate.com/perl-current/ bleadperl/

3.7) What is cfgperl? bleadperl? The mainline?

The repository of the Perl Perforce server is laid out something like this:

  /----+-----perl                 
       +-----cfgperl             
       +-----vmsperl               
       +-----maint-5.004------perl
       +-----maint-5.005------perl
       +-----maint-5.6------perl

Each "branch" contains an independent version of Perl, but Perforce
knows how to integrate patches between them.

The current development version of perl, otherwise known as bleadperl,
lives in the mainline, /perl. The Configure pumpking keeps his own
development version, at /cfgperl; this may be used to fix
Configure-related problems, or pick up development patches from p5p - or
whatever else the Configure pumpking wants to do with it. vmsperl is
there to fix VMS things, and the other branches are the maintenance
tracks for the named version. See Porting/perlforce.pod in your perl
distribution for more details.

3.7) How do I know which patch fixed my bug?

You can start with the Changes file from a development version of perl
(Either the latest 5.7.x or alternately,
rsync://ftp.linux.activestate.com/perl-current/Changes) and find which
change resolved your bug.

Some of the logged Changes have a bug ID attached to them - of the form
YYYYMMDD.NNN. That would be good to search for, as would be any topic
related to your bug. You can also search for this at http://bugs.perl.org/

You can look through the perl5-porters archives as well.
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ - search tips
would be possibly the subject of your original message, the bug ID, and
perhaps any keywords related to the problems your bug report addresses.

You can view the patch online by patch number at the repository browser,
http://public.activestate.com/cgi-bin/perlbrowse

(Thanks to Richard Soderburg for this answer.)

-----------------------------------------------------------------------
4) Who's Who

4.1) What's a pumpking?

You didn't read Porting/pumpkin.pod, did you? :) A pumpking is the
person who holds the patch pumpkin, the responsibility for co-ordinating
patches on a specific area. You can find a (slightly coded) list of the
current pumpkings at the end of AUTHORS in your Perl source kit - this
maps people to areas, and MAINTAIN maps both people and areas to files in
the kit.

4.2) What's *the* pumpking?

*The* pumpking is the person who holds the patch pumpkin for Perl
itself, what other projects call the "release engineer". Currently,
that's Jarkko Hietaniemi.

4.2) Who are the referees?

    Nathan Torkington   <gnat@frii.com>
    Chip Salzenberg     <chip@valinux.com>
    Mark-Jason Dominus  <mjd@plover.com>
    Damian Conway       <damian@conway.org>
    Kurt Starsinic      <kstar@cpan.org>

They have their own mailing list, <perl5-porters-referees@perl.org>,
but only referees may subscribe to that. If you have any issues with
the refereeing process, please try to sort it out with individual
referees first, and use the list as a last resort.

• FAQ! Read this first! by Simon Cozens
• Re: FAQ! Read this first! by Dave Mitchell