CONTENTS

• NAME
• DESCRIPTION
• SUPER QUICK PATCH GUIDE
• BUG REPORTING
• PERL 5 PORTERS
  • perl-changes mailing list
  • #p5p on IRC
• GETTING THE PERL SOURCE
  • Read access via Git
  • Read access via the web
  • Read access via rsync
  • Write access via git
• PATCHING PERL
  • Submitting patches
  • Getting your patch accepted
    • Patch style
    • Commit message
    • Comments, Comments, Comments
    • Style
    • Test suite
  • Patching a core module
  • Updating perldelta
  • What makes for a good patch?
    • Does the concept match the general goals of Perl?
    • Where is the implementation?
    • Backwards compatibility
    • Could it be a module instead?
    • Is the feature generic enough?
    • Does it potentially introduce new bugs?
    • How big is it?
    • Does it preclude other desirable features?
    • Is the implementation robust?
    • Is the implementation generic enough to be portable?
    • Is the implementation tested?
    • Is there enough documentation?
    • Is there another way to do it?
    • Does it create too much work?
    • Patches speak louder than words
• TESTING
  • Special make test targets
  • Parallel tests
  • Running tests by hand
  • Using t/harness for testing
    • Other environment variables that may influence tests
• MORE READING FOR GUTS HACKERS
• CPAN TESTERS AND PERL SMOKERS
• WHAT NEXT?
  • "The Road goes ever on and on, down from the door where it began."
  • Metaphoric Quotations
• AUTHOR

#NAME

perlhack - How to hack on Perl

#DESCRIPTION

This document explains how Perl development works. It includes details about the Perl 5 Porters email list, the Perl repository, the Perlbug bug tracker, patch guidelines, and commentary on Perl development philosophy.

#SUPER QUICK PATCH GUIDE

If you just want to submit a single small patch like a pod fix, a test for a bug, comment fixes, etc., it's easy! Here's how:

• Check out the source repository

  The perl source is in a git repository. You can clone the repository with the following command:

  % git clone git://perl5.git.perl.org/perl.git perl

• Ensure you're following the latest advice

  In case the advice in this guide has been updated recently, read the latest version directly from the perl source:

  % perldoc pod/perlhack.pod

• Make your change

  Hack, hack, hack.

• Test your change

  You can run all the tests with the following commands:

  % ./Configure -des -Dusedevel
  % make test

  Keep hacking until the tests pass.

• Commit your change

  Committing your work will save the change on your local system:

  % git commit -a -m 'Commit message goes here'

  Make sure the commit message describes your change in a single sentence. For example, "Fixed spelling errors in perlhack.pod".

• Send your change to perlbug

  The next step is to submit your patch to the Perl core ticket system via email.

  If your changes are in a single git commit, run the following commands to generate the patch file and attach it to your bug report:

  % git format-patch -1
  % ./perl -Ilib utils/perlbug -p 0001-*.patch

  The perlbug program will ask you a few questions about your email address and the patch you're submitting. Once you've answered them it will submit your patch via email.

  If your changes are in multiple commits, generate a patch file for each one and provide them to perlbug's -p option separated by commas:

  % git format-patch -3
  % ./perl -Ilib utils/perlbug -p 0001-fix1.patch,0002-fix2.patch,\
  > 0003-fix3.patch

  When prompted, pick a subject that summarizes your changes.

• Thank you

  The porters appreciate the time you spent helping to make Perl better. Thank you!

• Next time

  The next time you wish to make a patch, you need to start from the latest perl in a pristine state. Check you don't have any local changes or added files in your perl check-out which you wish to keep, then run these commands:

  % git pull
  % git reset --hard origin/blead
  % git clean -dxf

#BUG REPORTING

If you want to report a bug in Perl, you must use the perlbug command line tool. This tool will ensure that your bug report includes all the relevant system and configuration information.

To browse existing Perl bugs and patches, you can use the web interface at http://rt.perl.org/.

Please check the archive of the perl5-porters list (see below) and/or the bug tracking system before submitting a bug report. Often, you'll find that the bug has been reported already.

You can log in to the bug tracking system and comment on existing bug reports. If you have additional information regarding an existing bug, please add it. This will help the porters fix the bug.

#PERL 5 PORTERS

The perl5-porters (p5p) mailing list is where the Perl standard distribution is maintained and developed. The people who maintain Perl are also referred to as the "Perl 5 Porters", "p5p" or just the "porters".

A searchable archive of the list is available at http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/. There is also another archive at http://archive.develooper.com/[email protected]/.

#perl-changes mailing list

The perl5-changes mailing list receives a copy of each patch that gets submitted to the maintenance and development branches of the perl repository. See http://lists.perl.org/list/perl5-changes.html for subscription and archive information.