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
  • 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
  • Performance testing
  • Building perl at older commits
• 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 Perl 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 https://github.com/Perl/perl5.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

• Create a branch for your change

  Create a branch based on blead to commit your change to, which will later be used to send it to the Perl issue tracker.

  % git checkout -b mychange

• Make your change

  Hack, hack, hack. Keep in mind that Perl runs on many different platforms, with different operating systems that have different capabilities, different filesystem organizations, and even different character sets. perlhacktips gives advice on this.

• 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 the Perl issue tracker

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

  Create a GitHub fork of the perl5 repository and add it as a remote, if you haven't already, as described in the GitHub documentation at https://help.github.com/en/articles/working-with-forks.

  % git remote add fork [email protected]:MyUser/perl5.git

  For more information, see "Connecting to GitHub with SSH".

  If you'd rather use an HTTPS URL for your git push see "Cloning with HTTPS URLs".

  % git remote add fork https://github.com/MyUser/perl5.git

  Then, push your new branch to your fork.

  % git push -u fork mychange

  Finally, create a Pull Request on GitHub from your branch to blead as described in the GitHub documentation at https://help.github.com/en/articles/creating-a-pull-request-from-a-fork.

• Thank you

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

• Acknowledgement

  All contributors are credited (by name and email address) in the AUTHORS file, which is part of the perl distribution, as well as the Git commit history.

  If you don’t want to be included in the AUTHORS file, just let us know. Otherwise we will take your submission of a patch as permission to credit you in the AUTHORS file.

• 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 checkout blead
  % git pull
  % git reset --hard origin/blead
  % git clean -dxf

#BUG REPORTING

If you want to report a bug in Perl, or browse existing Perl bugs and patches, use the GitHub issue tracker at https://github.com/perl/perl5/issues.

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 https://markmail.org/search/?q=perl5-porters. There is also an archive at https://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 https://lists.perl.org/list/perl5-changes.html for subscription and archive information.

##p5p on IRC

Many porters are also active on the irc://irc.perl.org/#p5p channel. Feel free to join the channel and ask questions about hacking on the Perl core.

#GETTING THE PERL SOURCE

All of Perl's source code is kept centrally in a Git repository at github.com. The repository contains many Perl revisions from Perl 1 onwards and all the revisions from Perforce, the previous version control system.

For much more detail on using git with the Perl repository, please see perlgit.

#Read access via Git

You will need a copy of Git for your computer. You can fetch a copy of the repository using the git protocol:

% git clone [email protected]:Perl/perl5.git perl

This clones the repository and makes a local copy in the perl directory.

If you cannot use the git protocol for firewall reasons, you can also clone via http:

% git clone https://github.com/Perl/perl5.git perl

#Read access via the web

You may access the repository over the web. This allows you to browse the tree, see recent commits, subscribe to repository notifications, search for particular commits and more. You may access it at https://github.com/Perl/perl5.

#Write access via git

If you have a commit bit, please see perlgit for more details on using git.

#PATCHING PERL

If you're planning to do more extensive work than a single small fix, we encourage you to read the documentation below. This will help you focus your work and make your patches easier to incorporate into the Perl source.

#Submitting patches

If you have a small patch to submit, please submit it via the GitHub Pull Request workflow. You may also send patches to the p5p list.

Patches are reviewed and discussed on GitHub or the p5p list. Simple, uncontroversial patches will usually be applied without any discussion. When the patch is applied, the ticket will be updated and you will receive email.

In other cases, the patch will need more work or discussion. You are encouraged to participate in the discussion and advocate for your patch. Sometimes your patch may get lost in the shuffle. It's appropriate to send a reminder email to p5p if no action has been taken in a month. Please remember that the Perl 5 developers are all volunteers, and be polite.

Changes are always applied directly to the main development branch, called "blead". Some patches may be backported to a maintenance branch. If you think your patch is appropriate for the maintenance branch (see "MAINTENANCE BRANCHES" in perlpolicy), please explain why when you submit it.

#Getting your patch accepted

If you are submitting a code patch there are several things that you can do to help the Perl 5 Porters accept your patch.

#Patch style

Using the GitHub Pull Request workflow, your patch will automatically be available in a suitable format. If you wish to submit a patch to the p5p list for review, make sure to create it appropriately.

If you used git to check out the Perl source, then using git format-patch will produce a patch in a style suitable for Perl. The format-patch command produces one patch file for each commit you made. If you prefer to send a single patch for all commits, you can use git diff.

% git checkout blead
% git pull
% git diff blead my-branch-name

This produces a patch based on the difference between blead and your current branch. It's important to make sure that blead is up to date before producing the diff, that's why we call git pull first.

We strongly recommend that you use git if possible. It will make your life easier, and ours as well.

However, if you're not using git, you can still produce a suitable patch. You'll need a pristine copy of the Perl source to diff against. The porters prefer unified diffs. Using GNU diff, you can produce a diff like this:

% diff -Npurd perl.pristine perl.mine

Make sure that you make realclean in your copy of Perl to remove any build artifacts, or you may get a confusing result.

#