Edit: /usr/share/perl5/pod/perlhack.pod (43157B)
=encoding utf8
=for comment
Consistent formatting of this file is achieved with:
perl ./Porting/podtidy pod/perlhack.pod
=head1 NAME
perlhack - How to hack on Perl
=head1 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.
=head1 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:
=over 4
=item * 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
=item * 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
=item * 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
=item * 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. L
gives advice on this.
=item * Test your change
You can run all the tests with the following commands:
% ./Configure -des -Dusedevel
% make test
Keep hacking until the tests pass.
=item * Commit your change
Committing your work will save the change I:
% 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".
=item * 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
L.
% git remote add fork git@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
L.
=item * Thank you
The porters appreciate the time you spent helping to make Perl better.
Thank you!
=item * 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.
=item * 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
=back
=head1 BUG REPORTING
If you want to report a bug in Perl, or browse existing Perl bugs and
patches, use the GitHub issue tracker at
L.
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.
=head1 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
L. There is also an archive at
L.
=head2 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 L for
subscription and archive information.
=head2 #p5p on IRC
Many porters are also active on the L channel.
Feel free to join the channel and ask questions about hacking on the
Perl core.
=head1 GETTING THE PERL SOURCE
All of Perl's source code is kept centrally in a Git repository at
I. 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
L.
=head2 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 git://github.com/Perl/perl5.git perl
This clones the repository and makes a local copy in the F
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
=head2 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
L.
=head2 Read access via rsync
You can also choose to use rsync to get a copy of the current source
tree for the bleadperl branch and all maintenance branches:
% rsync -avz rsync://perl5.git.perl.org/perl-current .
% rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
(Add the C<--delete> option to remove leftover files.)
To get a full list of the available sync points:
% rsync perl5.git.perl.org::
=head2 Write access via git
If you have a commit bit, please see L for more details on
using git.
=head1 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.
=head2 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 L), please explain why
when you submit it.
=head2 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.
=head3 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 C will produce a patch in a style suitable for Perl. The
C command produces one patch file for each commit you
made. If you prefer to send a single patch for all commits, you can
use C.
% 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 C 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 C, you can produce a
diff like this:
% diff -Npurd perl.pristine perl.mine
Make sure that you C in your copy of Perl to remove any
build artifacts, or you may get a confusing result.
=head3 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.
=over 4
=item * 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.
=item * What
Your commit message should describe what part of the Perl core you're
changing and what you expect your patch to do.
=item * 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.
=back
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.
=head3 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 I the code does what it does, not I.
=head3 Style
In general, please follow the particular style of the code you are
patching.
In particular, follow these general guidelines for patching Perl
sources:
=over 4
=item *
4-wide indents for code, 2-wide indents for nested CPP C<#define>s,
with 8-wide tabstops.
=item *
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.
=item *
Try hard not to exceed 79-columns
=item *
ANSI C prototypes
=item *
Uncuddled elses and "K&R" style for indenting control constructs
=item *
No C++ style (//) comments
=item *
Mark places that need to be revisited with XXX (and revisit often!)
=item *
Opening brace lines up with "if" when conditional spans multiple lines;
should be at end-of-line otherwise
=item *
In function definitions, name starts in column 0 (return value-type is on
previous line)
=item *
Single space after keywords that are followed by parens, no space
between function name and following paren
=item *
Avoid assignments in conditionals, but if they're unavoidable, use
extra paren, e.g. "if (a && (b = c)) ..."
=item *
"return foo;" rather than "return(foo);"
=item *
"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
=item *
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.
=item *
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 C<-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.
=back
=head3 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 ):
=over 4
=item *
Know what you're testing. Read the docs, and the source.
=item *
Tend to fail, not succeed.
=item *
Interpret results strictly.
=item *
Use unrelated features (this will flush out bizarre interactions).
=item *
Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
=item *
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).
=item *
Give meaningful error messages when a test fails.
=item *
Avoid using qx// and system() unless you are testing for them. If you
do use them, make sure that you cover _all_ perl platforms.
=item *
Unlink any temporary files you create.
=item *
Promote unforeseen warnings to errors with $SIG{__WARN__}.
=item *
Be sure to use the libraries and modules shipped with the version being
tested, not those that were already installed.
=item *
Add comments to the code explaining what you are testing for.
=item *
Make updating the '1..42' string unnecessary. Or make sure that you
update it.
=item *
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.
=back
=head2 Patching a core module
This works just like patching anything else, with one extra
consideration.
Modules in the F 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 L for more
information on reporting bugs and submitting patches.
In most cases, patches to modules in F should be sent upstream
and should not be applied to the Perl core individually. If a patch to
a file in F absolutely cannot wait for the fix to be made
upstream, released to CPAN and copied to blead, you must add (or
update) a C entry in the F<"Porting/Maintainers.pl"> file
to flag that a local modification has been made. See
F<"Porting/Maintainers.pl"> for more details.
In contrast, modules in the F directory are maintained in the
core.
=head2 Updating perldelta
For changes significant enough to warrant a F 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:
=over 4
=item *
Adding, deprecating, or removing core features
=item *
Adding, deprecating, removing, or upgrading core or dual-life modules
=item *
Adding new core tests
=item *
Fixing security issues and user-visible bugs in the core
=item *
Changes that might break existing code, either on the perl or C level
=item *
Significant performance improvements
=item *
Adding, removing, or significantly changing documentation in the
F directory
=item *
Important platform-specific changes
=back
Please make sure you add the perldelta entry to the right section
within F. More information on how to write good
perldelta entries is available in the C