=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 Perlbug 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 git://perl5.git.perl.org/perl.git perl =item * Make your change Hack, hack, hack. =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 perlbug The next step is to submit your patch to the Perl core ticket system via email. Assuming your patch consists of a single git commit, the following writes the file as a MIME attachment, and sends it with a meaningful subject: % git format-patch -1 --attach % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch 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. =item * Thank you The porters appreciate the time you spent helping to make Perl better. Thank you! =back =head1 BUG REPORTING If you want to report a bug in Perl, you must use the F 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. 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 another 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://perl5.git.perl.org/perl.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, though this is much slower: % git clone http://perl5.git.perl.org/perl.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, search for particular commits and more. You may access it at L. A mirror of the repository is found 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 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. Patches are reviewed and discussed on 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. 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, 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 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 * 8-wide tabs (no exceptions!) =item * 4-wide indents for code, 2-wide indents for nested CPP #defines =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 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. =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