X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/5b48d9bbd702cd2c0a0863c898b3d4b120daf256..84788b0ad520f8ccb85c0aebc0f12136e3c26ee7:/pod/perlhack.pod diff --git a/pod/perlhack.pod b/pod/perlhack.pod index e5347ff..ff685d2 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -10,7 +10,7 @@ perlhack - How to hack on Perl =head1 DESCRIPTION -This document explains how Perl development works. It includes details +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. @@ -24,11 +24,18 @@ for a bug, comment fixes, etc., it's easy! Here's how: =item * Check out the source repository -The perl source is in a git repository. You can clone the 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 * 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 * Make your change Hack, hack, hack. @@ -49,57 +56,78 @@ 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". +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 +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 format-patch -1 --attach - % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch + % ./perl -Ilib utils/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 +address and the patch you're submitting. Once you've answered them it will submit your patch via email. +If your changes are in multiple commits, generate a patch file +containing them all, and attach that: + + % git format-patch origin/blead --attach --stdout > patches + % ./perl -Ilib utils/perlbug -f patches + +When prompted, pick a subject that summarizes your changes overall and +has "[PATCH]" at the beginning. + =item * Thank you The porters appreciate the time you spent helping to make Perl better. Thank you! +=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 pull + % git reset --hard origin/blead + % git clean -dxf + =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 +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 +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. +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 +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 +L. There is also another archive at L. @@ -107,7 +135,7 @@ L. 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 +repository. See L for subscription and archive information. =head2 #p5p on IRC @@ -119,8 +147,8 @@ 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 +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 @@ -128,7 +156,7 @@ L. =head2 Read access via Git -You will need a copy of Git for your computer. You can fetch a copy of +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 @@ -143,10 +171,10 @@ clone via http, though this is much slower: =head2 Read access via the web -You may access the repository over the web. This allows you to browse +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 +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 @@ -154,18 +182,18 @@ found at L. 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 . + % 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:: + % rsync perl5.git.perl.org:: =head2 Write access via git @@ -175,40 +203,40 @@ 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 +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 +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 +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 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. +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 +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 +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 +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. +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 @@ -218,25 +246,25 @@ 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 +format-patch> 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. +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 +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 +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 +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 @@ -247,11 +275,11 @@ 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 +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 +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 @@ -271,11 +299,11 @@ to Perl. =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 +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 +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. @@ -294,23 +322,23 @@ 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 +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, +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 +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. +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. @@ -393,8 +421,8 @@ 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. +these extra flags is to catch potential problems in legal C code, and +is often used by Perl aggregators, such as Linux distributors. =back @@ -402,7 +430,7 @@ often used by Perl aggregators, such as Linux distributors. 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 +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. @@ -413,7 +441,7 @@ Your test suite additions should generally follow these guidelines =item * -Know what you're testing. Read the docs, and the source. +Know what you're testing. Read the docs, and the source. =item * @@ -443,7 +471,7 @@ Give meaningful error messages when a test fails. =item * -Avoid using qx// and system() unless you are testing for them. If you +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 * @@ -465,7 +493,7 @@ Add comments to the code explaining what you are testing for. =item * -Make updating the '1..42' string unnecessary. Or make sure that you +Make updating the '1..42' string unnecessary. Or make sure that you update it. =item * @@ -488,7 +516,7 @@ 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 +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. @@ -508,8 +536,8 @@ core. 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: +along with your actual change. Significant changes include, but are +not limited to: =over 4 @@ -549,13 +577,13 @@ 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 +within F. More information on how to write good perldelta entries is available in the C