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.

#Commit message

As you craft each patch you intend to submit to the Perl core, it's important to write a good commit message. This is especially important if your submission will consist of a series of commits.

The first line of the commit message should be a short description without a period. It should be no longer than the subject line of an email, 50 characters being a good rule of thumb.

A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will only display the first line (cut off at 50 characters) when presenting commit summaries.

The commit message should include a description of the problem that the patch corrects or new functionality that the patch adds.

As a general rule of thumb, your commit message should help a programmer who knows the Perl core quickly understand what you were trying to do, how you were trying to do it, and why the change matters to Perl.

• Why

  Your commit message should describe why the change you are making is important. When someone looks at your change in six months or six years, your intent should be clear.

  If you're deprecating a feature with the intent of later simplifying another bit of code, say so. If you're fixing a performance problem or adding a new feature to support some other bit of the core, mention that.

• What

  Your commit message should describe what part of the Perl core you're changing and what you expect your patch to do.

• How

  While it's not necessary for documentation changes, new tests or trivial patches, it's often worth explaining how your change works. Even if it's clear to you today, it may not be clear to a porter next month or next year.

A commit message isn't intended to take the place of comments in your code. Commit messages should describe the change you made, while code comments should describe the current state of the code.

If you've just implemented a new feature, complete with doc, tests and well-commented code, a brief commit message will often suffice. If, however, you've just changed a single character deep in the parser or lexer, you might need to write a small novel to ensure that future readers understand what you did and why you did it.

#Comments, Comments, Comments

Be sure to adequately comment your code. While commenting every line is unnecessary, anything that takes advantage of side effects of operators, that creates changes that will be felt outside of the function being patched, or that others may find confusing should be documented. If you are going to err, it is better to err on the side of adding too many comments than too few.

The best comments explain why the code does what it does, not what it does.

#Style

In general, please follow the particular style of the code you are patching.

In particular, follow these general guidelines for patching Perl sources:

• 4-wide indents for code, 2-wide indents for nested CPP #defines, with 8-wide tabstops.

• Use spaces for indentation, not tab characters.

  The codebase is a mixture of tabs and spaces for indentation, and we are moving to spaces only. Converting lines you're patching from 8-wide tabs to spaces will help this migration.

• Try not to exceed 79 columns

  In general, we target 80 column lines. When sticking to 80 columns would lead to torturous code or rework, it's fine to go longer. Try to keep your excess past 80 to a minimum.

• ANSI C prototypes

• Uncuddled elses and "K&R" style for indenting control constructs

• No C++ style (//) comments

• Mark places that need to be revisited with XXX (and revisit often!)

• Opening brace lines up with "if" when conditional spans multiple lines; should be at end-of-line otherwise

• In function definitions, name starts in column 0 (return value-type is on previous line)

• Single space after keywords that are followed by parens, no space between function name and following paren

• Avoid assignments in conditionals, but if they're unavoidable, use extra paren, e.g. "if (a && (b = c)) ..."

• "return foo;" rather than "return(foo);"

• "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.

• Do not declare variables using "register". It may be counterproductive with modern compilers, and is deprecated in C++, under which the Perl source is regularly compiled.

• In-line functions that are in headers that are accessible to XS code need to be able to compile without warnings with commonly used extra compilation flags, such as gcc's -Wswitch-default which warns whenever a switch statement does not have a "default" case. The use of these extra flags is to catch potential problems in legal C code, and is often used by Perl aggregators, such as Linux distributors.

#Test suite

If your patch changes code (rather than just changing documentation), you should also include one or more test cases which illustrate the bug you're fixing or validate the new functionality you're adding. In general, you should update an existing test file rather than create a new one.

Your test suite additions should generally follow these guidelines (courtesy of Gurusamy Sarathy <[email protected]>):

• Know what you're testing. Read the docs, and the source.

• Tend to fail, not succeed.

• Interpret results strictly.

• Use unrelated features (this will flush out bizarre interactions).

• Use non-standard idioms (otherwise you are not testing TIMTOWTDI).

• Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT found in t/op/tie.t is much more maintainable, and gives better failure reports).

• Give meaningful error messages when a test fails.

• Avoid using qx// and system() unless you are testing for them. If you do use them, make sure that you cover _all_ perl platforms.

• Unlink any temporary files you create.

• Promote unforeseen warnings to errors with $SIG{__WARN__}.

• Be sure to use the libraries and modules shipped with the version being tested, not those that were already installed.

• Add comments to the code explaining what you are testing for.

• Make updating the '1..42' string unnecessary. Or make sure that you update it.

• Test _all_ behaviors of a given operator, library, or function.

  Test all optional arguments.

  Test return values in various contexts (boolean, scalar, list, lvalue).

  Use both global and lexical variables.

  Don't forget the exceptional, pathological cases.

#Patching a core module

This works just like patching anything else, with one extra consideration.

Modules in the cpan/ directory of the source tree are maintained outside of the Perl core. When the author updates the module, the updates are simply copied into the core. See that module's documentation or its listing on https://metacpan.org/ for more information on reporting bugs and submitting patches.

In most cases, patches to modules in cpan/ should be sent upstream and should not be applied to the Perl core individually. If a patch to a file in cpan/ absolutely cannot wait for the fix to be made upstream, released to CPAN and copied to blead, you must add (or update) a CUSTOMIZED entry in the Porting/Maintainers.pl file to flag that a local modification has been made. See Porting/Maintainers.pl for more details.

In contrast, modules in the dist/ directory are maintained in the core.

#Updating perldelta

For changes significant enough to warrant a pod/perldelta.pod entry, the porters will greatly appreciate it if you submit a delta entry along with your actual change. Significant changes include, but are not limited to:

• Adding, deprecating, or removing core features

• Adding, deprecating, removing, or upgrading core or dual-life modules

• Adding new core tests

• Fixing security issues and user-visible bugs in the core

• Changes that might break existing code, either on the perl or C level

• Significant performance improvements

• Adding, removing, or significantly changing documentation in the pod/ directory

• Important platform-specific changes

Please make sure you add the perldelta entry to the right section within pod/perldelta.pod. More information on how to write good perldelta entries is available in the Style section of Porting/how_to_write_a_perldelta.pod.

#What makes for a good patch?

New features and extensions to the language can be contentious. There is no specific set of criteria which determine what features get added, but here are some questions to consider when developing a patch:

#Does the concept match the general goals of Perl?

Our goals include, but are not limited to:

1. Keep it fast, simple, and useful.

2. Keep features/concepts as orthogonal as possible.

3. No arbitrary limits (platforms, data sizes, cultures).

4. Keep it open and exciting to use/patch/advocate Perl everywhere.

5. Either assimilate new technologies, or build bridges to them.

#