=head1 DESCRIPTION
This document explains how Perl development works. It includes details
-about the Perl 5 Porters email list, the Perl repository, the Perlbug
+about the Perl 5 Porters email list, the Perl repository, the Perl
bug tracker, patch guidelines, and commentary on Perl development
philosophy.
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
+ % git clone https://github.com/Perl/perl5.git perl
=item * Ensure you're following the latest advice
% 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.
+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<perlhacktips> gives advice on this.
=item * Test your change
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 perlbug
+=item * Send your change to the Perl issue tracker
+
+The next step is to submit your patch to the Perl core ticket system.
-The next step is to submit your patch to the Perl core ticket system
-via email.
+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<https://help.github.com/en/articles/working-with-forks>.
-If your changes are in a single git commit, run the following commands
-to write the file as a MIME attachment and send it with a meaningful
-subject:
+ % git remote add fork git@github.com:MyUser/perl5.git
- % git format-patch -1 --attach
- % ./perl -Ilib utils/perlbug -s "[PATCH] $(
- git log -1 --oneline HEAD)" -f 0001-*.patch
+For more information, see L<"Connecting to GitHub with SSH"|https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh>.
-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 you'd rather use an HTTPS URL for your C<git push> see L<"Cloning with
+HTTPS URLs"|https://docs.github.com/en/free-pro-team@latest/github/using-git/which-remote-url-should-i-use#cloning-with-https-urls>.
-If your changes are in multiple commits, generate a patch file
-containing them all, and attach that:
+ % git remote add fork https://github.com/MyUser/perl5.git
- % git format-patch origin/blead --attach --stdout > patches
- % ./perl -Ilib utils/perlbug -f patches
+Then, push your new branch to your fork.
-When prompted, pick a subject that summarizes your changes overall and
-has "[PATCH]" at the beginning.
+ % 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<https://help.github.com/en/articles/creating-a-pull-request-from-a-fork>.
=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
+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
=head1 BUG REPORTING
-If you want to report a bug in Perl, you must use the F<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 L<http://rt.perl.org/>.
+If you want to report a bug in Perl, or browse existing Perl bugs and
+patches, use the GitHub issue tracker at
+L<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
"porters".
A searchable archive of the list is available at
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
-also another archive at
-L<http://archive.develooper.com/perl5-porters@perl.org/>.
+L<https://markmail.org/search/?q=perl5-porters>. There is also an archive at
+L<https://archive.develooper.com/perl5-porters@perl.org/>.
=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<http://lists.perl.org/list/perl5-changes.html> for
+repository. See L<https://lists.perl.org/list/perl5-changes.html> for
subscription and archive information.
=head2 #p5p on IRC
=head1 GETTING THE PERL SOURCE
All of Perl's source code is kept centrally in a Git repository at
-I<perl5.git.perl.org>. The repository contains many Perl revisions
+I<github.com>. The repository contains many Perl revisions
from Perl 1 onwards and all the revisions from Perforce, the previous
version control system.
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://perl5.git.perl.org/perl.git perl
+ % git clone git://github.com/Perl/perl5.git perl
This clones the repository and makes a local copy in the F<perl>
directory.
If you cannot use the git protocol for firewall reasons, you can also
-clone via http, though this is much slower:
+clone via http:
- % git clone http://perl5.git.perl.org/perl.git perl
+ % 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 RSS feeds for the changes,
+the tree, see recent commits, subscribe to repository notifications,
search for particular commits and more. You may access it at
-L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is
-found at L<http://github.com/mirrors/perl>.
+L<https://github.com/Perl/perl5>.
=head2 Read access via rsync
=head2 Submitting patches
-If you have a small patch to submit, please submit it via perlbug. You
-can also send email directly to perlbug@perl.org. Please note that
-messages sent to perlbug may be held in a moderation queue, so you
-won't receive a response immediately.
+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.
-You'll know your submission has been processed when you receive an
-email from our ticket tracking system. This email will give you a
-ticket number. Once your patch has made it to the ticket tracking
-system, it will also be sent to the perl5-porters@perl.org list.
-
-Patches are reviewed and discussed on the p5p list. Simple,
+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 addition, an email will be sent to the p5p list.
-
-In other cases, the patch will need more work or discussion. That will
-happen on the p5p list.
+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
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, please explain why when you submit it.
+branch. If you think your patch is appropriate for the maintenance
+branch (see L<perlpolicy/MAINTENANCE BRANCHES>), please explain why
+when you submit it.
=head2 Getting your patch accepted
=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<git
format-patch> will produce a patch in a style suitable for Perl. The
C<format-patch> command produces one patch file for each commit you
=item *
-8-wide tabs (no exceptions!)
+4-wide indents for code, 2-wide indents for nested CPP C<#define>s,
+with 8-wide tabstops.
=item *
-4-wide indents for code, 2-wide indents for nested CPP #defines
+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 *
=item *
-In function definitions, name starts in column 0 (return value is on
+In function definitions, name starts in column 0 (return value-type is on
previous line)
=item *
Modules in the F<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 L<http://search.cpan.org/> for more
+documentation or its listing on L<https://metacpan.org/> for more
information on reporting bugs and submitting patches.
In most cases, patches to modules in F<cpan/> should be sent upstream
Good patches (tight code, complete, correct) stand more chance of going
in. Sloppy or incorrect patches might be placed on the back burner
-until the pumpking has time to fix, or might be discarded altogether
+until fixes can be made, or they might be discarded altogether
without further notice.
=head3 Is the implementation generic enough to be portable?
=head3 Does it create too much work?
-Work for the pumpking, work for Perl programmers, work for module
+Work for the committers, work for Perl programmers, work for module
authors, ... Perl is supposed to be easy.
=head3 Patches speak louder than words
features as possible.
If you write your own test, use the L<Test Anything
-Protocol|http://testanything.org>.
+Protocol|https://testanything.org>.
=over 4
=item * F<t/base>, F<t/comp> and F<t/opbasic>
-Since we don't know if require works, or even subroutines, use ad hoc
+Since we don't know if C<require> works, or even subroutines, use ad hoc
tests for these three. Step carefully to avoid using the feature being
tested. Tests in F<t/opbasic>, for instance, have been placed there
rather than in F<t/op> because they test functionality which
F<t/test.pl> presumes has already been demonstrated to work.
-=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op>
+=item * All other subdirectories of F<t/>
Now that basic require() and subroutines are tested, you can use the
F<t/test.pl> library.
-You can also use certain libraries like Config conditionally, but be
+You can also use certain libraries like L<Config> conditionally, but be
sure to skip the test gracefully if it's not there.
-=item * Everything else
+=item * Test files not found under F<t/>
-Now that the core of Perl is tested, L<Test::More> can and should be
-used. You can also use the full suite of core modules in the tests.
+This category includes F<.t> files underneath directories such as F<dist>,
+F<ext> and F<lib>. Since the core of Perl has now been tested, L<Test::More>
+can and now should be used. You can also use the full suite of core modules
+in the tests. (As noted in L<"Patching a core module"> above, changes to
+F<.t> files found under F<cpan/> should be submitted to the upstream
+maintainers of those modules.)
=back
F<lib/>, so here's some opportunity for some patching.
You must be triply conscious of cross-platform concerns. This usually
-boils down to using L<File::Spec> and avoiding things like C<fork()>
-and C<system()> unless absolutely necessary.
+boils down to using L<File::Spec>, avoiding things like C<fork()>
+and C<system()> unless absolutely necessary, and not assuming that a
+given character has a particular ordinal value (code point) or that its
+UTF-8 representation is composed of particular bytes.
+
+There are several functions available to specify characters and code
+points portably in tests. The always-preloaded functions
+C<utf8::unicode_to_native()> and its inverse
+C<utf8::native_to_unicode()> take code points and translate
+appropriately. The file F<t/charset_tools.pl> has several functions
+that can be useful. It has versions of the previous two functions
+that take strings as inputs -- not single numeric code points:
+C<uni_to_native()> and C<native_to_uni()>. If you must look at the
+individual bytes comprising a UTF-8 encoded string,
+C<byte_utf8a_to_utf8n()> takes as input a string of those bytes encoded
+for an ASCII platform, and returns the equivalent string in the native
+platform. For example, C<byte_utf8a_to_utf8n("\xC2\xA0")> returns the
+byte sequence on the current platform that form the UTF-8 for C<U+00A0>,
+since C<"\xC2\xA0"> are the UTF-8 bytes on an ASCII platform for that
+code point. This function returns C<"\xC2\xA0"> on an ASCII platform, and
+C<"\x80\x41"> on an EBCDIC 1047 one.
+
+But easiest is, if the character is specifiable as a literal, like
+C<"A"> or C<"%">, to use that; if not so specificable, you can use
+C<\N{}> , if the side effects aren't troublesome. Simply specify all
+your characters in hex, using C<\N{U+ZZ}> instead of C<\xZZ>. C<\N{}>
+is the Unicode name, and so it
+always gives you the Unicode character. C<\N{U+41}> is the character
+whose Unicode code point is C<0x41>, hence is C<'A'> on all platforms.
+The side effects are:
+
+=over 4
+
+=item *
+
+These select Unicode rules. That means that in double-quotish strings,
+the string is always converted to UTF-8 to force a Unicode
+interpretation (you can C<utf8::downgrade()> afterwards to convert back
+to non-UTF8, if possible). In regular expression patterns, the
+conversion isn't done, but if the character set modifier would
+otherwise be C</d>, it is changed to C</u>.
+
+=item *
+
+If you use the form C<\N{I<character name>}>, the L<charnames> module
+gets automatically loaded. This may not be suitable for the test level
+you are doing.
+
+=back
+
+If you are testing locales (see L<perllocale>), there are helper
+functions in F<t/loc_tools.pl> to enable you to see what locales there
+are on the current platform.
=head2 Special C<make test> targets
Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
F<t/op>, F<t/uni> and F<t/mro> tests.
+F<miniperl> is a minimalistic perl built to bootstrap building
+extensions, utilties, documentation etc. It doesn't support dynamic
+loading and depending on the point in the build process will only have
+access to a limited set of core modules. F<miniperl> is not intended
+for day to day use.
+
=item * test.valgrind check.valgrind
(Only in Linux) Run all the tests using the memory leak + naughty
=head2 Parallel tests
The core distribution can now run its regression tests in parallel on
-Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
-in your environment to the number of tests to run in parallel, and run
-C<make test_harness>. On a Bourne-like shell, this can be done as
+Unix-like and Windows platforms. On Unix, instead of running C<make
+test>, set C<TEST_JOBS> in your environment to the number of tests to
+run in parallel, and run C<make test_harness>. On a Bourne-like shell,
+this can be done as
TEST_JOBS=3 make test_harness # Run 3 tests in parallel
non-conflicting test scripts itself, and there is no standard interface
to C<make> utilities to interact with their job schedulers.
-Note that currently some test scripts may fail when run in parallel
-(most notably F<ext/IO/t/io_dir.t>). If necessary, run just the
-failing scripts again sequentially and see if the failures go away.
+Tests are normally run in a logical order, with the sanity tests first,
+then the main tests of the Perl core functionality, then the tests for
+the non-core modules. On many-core systems, this may not use the
+hardware as effectively as possible. By also specifying
+
+ TEST_JOBS=19 PERL_TEST_HARNESS_ASAP=1 make -j19 test_harness
+
+you signal that you want the tests to finish in wall-clock time as short
+as possible. After the sanity tests are completed, this causes the
+remaining ones to be packed into the available cores as tightly as
+we know how. This has its greatest effect on slower, many-core systems.
+Throughput was sped up by 20% on an outmoded 24-core system; less on
+more recent faster ones with fewer cores.
+
+Note that the command line above added a C<-j> parameter to make, so as
+to cause parallel compilation. This may or may not work on your
+platform.
=head2 Running tests by hand
See also the documentation for the Test and Test::Harness modules, for
more environment variables that affect testing.
+=head2 Performance testing
+
+The file F<t/perf/benchmarks> contains snippets of perl code which are
+intended to be benchmarked across a range of perls by the
+F<Porting/bench.pl> tool. If you fix or enhance a performance issue, you
+may want to add a representative code sample to the file, then run
+F<bench.pl> against the previous and current perls to see what difference
+it has made, and whether anything else has slowed down as a consequence.
+
+The file F<t/perf/opcount.t> is designed to test whether a particular
+code snippet has been compiled into an optree containing specified
+numbers of particular op types. This is good for testing whether
+optimisations which alter ops, such as converting an C<aelem> op into an
+C<aelemfast> op, are really doing that.
+
+The files F<t/perf/speed.t> and F<t/re/speed.t> are designed to test
+things that run thousands of times slower if a particular optimisation
+is broken (for example, the utf8 length cache on long utf8 strings).
+Add a test that will take a fraction of a second normally, and minutes
+otherwise, causing the test file to time out on failure.
+
+=head2 Building perl at older commits
+
+In the course of hacking on the Perl core distribution, you may have occasion
+to configure, build and test perl at an old commit. Sometimes C<make> will
+fail during this process. If that happens, you may be able to salvage the
+situation by using the Devel::PatchPerl library from CPAN (not included in the
+core) to bring the source code at that commit to a buildable state.
+
+Here's a real world example, taken from work done to resolve
+L<perl #10118|https://github.com/Perl/perl5/issues/10118>.
+Use of F<Porting/bisect.pl> had identified commit
+C<ba77e4cc9d1ceebf472c9c5c18b2377ee47062e6> as the commit in which a bug was
+corrected. To confirm, a P5P developer wanted to configure and build perl at
+commit C<ba77e4c^> (presumably "bad") and then at C<ba77e4c> (presumably
+"good"). Normal configuration and build was attempted:
+
+ $ sh ./Configure -des -Dusedevel
+ $ make test_prep
+
+C<make>, however, failed with output (excerpted) like this:
+
+ cc -fstack-protector -L/usr/local/lib -o miniperl \
+ gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \
+ mg.o reentr.o mro.o hv.o av.o run.o pp_hot.o sv.o \
+ pp.o scope.o pp_ctl.o pp_sys.o doop.o doio.o regexec.o \
+ utf8.o taint.o deb.o universal.o globals.o perlio.o \
+ numeric.o mathoms.o locale.o pp_pack.o pp_sort.o \
+ miniperlmain.o opmini.o perlmini.o
+ pp.o: In function `Perl_pp_pow':
+ pp.c:(.text+0x2db9): undefined reference to `pow'
+ ...
+ collect2: error: ld returned 1 exit status
+ makefile:348: recipe for target 'miniperl' failed
+ make: *** [miniperl] Error 1
+
+Another P5P contributor recommended installation and use of Devel::PatchPerl
+for this situation, first to determine the version of perl at the commit in
+question, then to patch the source code at that point to facilitate a build.
+
+ $ perl -MDevel::PatchPerl -e \
+ 'print Devel::PatchPerl->determine_version("/path/to/sourcecode"), "\n";'
+ 5.11.1
+ $ perl -MDevel::PatchPerl -e \
+ 'Devel::PatchPerl->patch_source("5.11.1", "/path/to/sourcecode");'
+
+Once the source was patched, C<./Configure> and C<make test_prep> were called
+and completed successfully, enabling confirmation of the findings in RT
+#72414.
+
=head1 MORE READING FOR GUTS HACKERS
To hack on the Perl guts, you'll need to read the following things:
Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very
helpful pictures:
-L<http://search.cpan.org/dist/illguts/>
+L<https://metacpan.org/release/RURBAN/illguts-0.49>
=item * L<perlxstut> and L<perlxs>
=item * F<Porting/pumpkin.pod>
This is a collection of words of wisdom for a Perl porter; some of it
-is only useful to the pumpkin holder, but most of it applies to anyone
+is only useful to the pumpkin holders, but most of it applies to anyone
wanting to go about Perl development.
=back
=head1 CPAN TESTERS AND PERL SMOKERS
-The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers
+The CPAN testers ( L<http://cpantesters.org/> ) are a group of volunteers
who test CPAN modules on a variety of platforms.
-Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and
-http://www.nntp.perl.org/group/perl.daily-build.reports/ )
+Perl Smokers ( L<https://www.nntp.perl.org/group/perl.daily-build/> and
+L<https://www.nntp.perl.org/group/perl.daily-build.reports/> )
automatically test Perl source releases on platforms with various
configurations.
Both efforts welcome volunteers. In order to get involved in smoke
testing of the perl itself visit
-L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke
+L<https://metacpan.org/release/Test-Smoke>. In order to start smoke
testing CPAN modules visit
-L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or
-L<http://search.cpan.org/dist/minismokebox/> or
-L<http://search.cpan.org/dist/CPAN-Reporter/>.
+L<https://metacpan.org/release/CPANPLUS-YACSmoke> or
+L<https://metacpan.org/release/minismokebox> or
+L<https://metacpan.org/release/CPAN-Reporter>.
=head1 WHAT NEXT?
This document was originally written by Nathan Torkington, and is
maintained by the perl5-porters mailing list.
-
https://perl5.git.perl.org / perl5.git / blobdiff