=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. Keep in mind that Perl runs on many different
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.
+
+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>.
-The next step is to submit your patch to the Perl core ticket system
-via email.
+ % git remote add fork git@github.com:MyUser/perl5.git
-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:
+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>.
- % git format-patch -1
- % ./perl -Ilib utils/perlbug -p 0001-*.patch
+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>.
-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.
+ % git remote add fork https://github.com/MyUser/perl5.git
-If your changes are in multiple commits, generate a patch file for each
-one and provide them to perlbug's C<-p> option separated by commas:
+Then, push your new branch to your fork.
- % git format-patch -3
- % ./perl -Ilib utils/perlbug -p 0001-fix1.patch,0002-fix2.patch,\
- > 0003-fix3.patch
+ % git push -u fork mychange
-When prompted, pick a subject that summarizes your changes.
+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
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://markmail.org/search/?q=perl5-porters>. There is also an 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<https://github.com/Perl/perl5>.
+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.
-
-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.
+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 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
=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
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
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
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 use
+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
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<dist/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
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 #72414|https://rt.perl.org/Ticket/Display.html?id=72414>.
+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
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 \
- perlapi.o numeric.o mathoms.o locale.o pp_pack.o pp_sort.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'
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 ( L<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 ( L<http://www.nntp.perl.org/group/perl.daily-build/> and
-L<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?
https://perl5.git.perl.org / perl5.git / blobdiff