From 04c692a854b61dfae1266e29468ce4fb51c80512 Mon Sep 17 00:00:00 2001 From: Dave Rolsky Date: Mon, 31 Jan 2011 16:15:24 -0600 Subject: [PATCH] Major revision of perlhack and perlrepository The existing perlhack is huge and takes a long time to get to key information like "how to submit a patch". It also contains a massive amount of (very useful) detail on the Perl interpreter, debugging, portability issues, and so on. Some parts of perlhack are just obsolete. For example, Larry really isn't deeply involved on p5p any more. Meanwhile, perlrepository _also_ contains a lot of useful information on patching Perl, as well as a small git tutorial focused on working with the Perl repository. Taken together, the two documents overlap and conflict with each other. This commit does the following: == Reconcile conflicts and overlaps, remove obsolete information I've separated out distinct pieces of information and organized them into individual pod files. More on that below. I've also removed anything that was obviously out of date. == Make it easier for casual contributors to contribute. The perlhack document now gets to "how to make a patch" very quickly. My assumption is that most contributors to Perl are doing something small, like fixing pod, adding a test, etc. The documentation aimed at people doing more extensive hacking is still there, but it's been moved so that it comes at the end of the document or has been moved to another document. I've made an effort to cross-reference the various documents so that nothing gets lost. == Get to the point The perlhack document had a lot of discussion of general Perl culture. I've trimmed a lot of this and moved some of it so it comes later. == Per-file summary === perlrepository.pod This is gone. Some of its content is now in perlhack. This includes the bits on writing good commit messages, how (and where) to submit a patch, etc. The rest is now called perlgit, and is _only_ a git how-to. === perlhack.pod This has been cut down quite a bit. I changed the opening so it starts with a quick guide to submitting small patches. The document covers bug reporting, the p5p list, a quick how-to on getting the source (including git, gitweb, and rsync), and a lot of general information on patching perl and running tests. Much of this material was already present, but I've done a fair amount of editing for modernization and clarity. Most of the information specific to C-level hacking has been moved to other documents. === perlsource.pod This is a guide to the Perl source tree. Most of the content was extracted from perlhack. I've edited existing content and added details on some parts of the tree that weren't covered. === perlinterp.pod This is a tour of the Perl interpreter source and a walkthrough of how it works that originally lived in perlhack. This has received very little editing. === perlhacktut.pod This is a walkthrough of creating a sample patch to the C core code that originally lived in perlhack. This has received very little editing. === perlhacktips.pod The perlhack document contained a lot of useful information on low-level hacking details like debugging, compilation issues, portability, etc. This has received very little editing. I did remove some bits on ancient stuff related to Tru64 and IRIX. --- MANIFEST | 6 +- pod.lst | 6 +- pod/perl.pod | 6 +- pod/perldelta.pod | 15 +- pod/{perlrepository.pod => perlgit.pod} | 832 +++---- pod/perlhack.pod | 3654 ++++++------------------------- pod/perlhacktips.pod | 1459 ++++++++++++ pod/perlhacktut.pod | 188 ++ pod/perlinterp.pod | 742 +++++++ pod/perlsource.pod | 216 ++ vms/descrip_mms.template | 60 +- win32/pod.mak | 24 +- 12 files changed, 3701 insertions(+), 3507 deletions(-) rename pod/{perlrepository.pod => perlgit.pod} (62%) create mode 100644 pod/perlhacktips.pod create mode 100644 pod/perlhacktut.pod create mode 100644 pod/perlinterp.pod create mode 100644 pod/perlsource.pod diff --git a/MANIFEST b/MANIFEST index 6831b0d..b7c88f8 100644 --- a/MANIFEST +++ b/MANIFEST @@ -4320,11 +4320,15 @@ pod/perlfilter.pod Perl source filters pod/perlfork.pod Perl fork() information pod/perlform.pod Perl formats pod/perlfunc.pod Perl built-in functions +pod/perlgit.pod Using git with the Perl repository pod/perlglossary.pod Perl Glossary pod/perlgpl.pod GNU General Public License pod/perlguts.pod Perl internal functions for those doing extensions pod/perlhack.pod Perl hackers guide +pod/perlhacktips.pod Tips for Perl core C code hacking +pod/perlhacktut.pod Walk through the creation of a simple C code patch pod/perlhist.pod Perl history records +pod/perlinterp.pod Overview of the Perl intepreter source and how it works pod/perlintro.pod Perl introduction for beginners pod/perliol.pod C API for Perl's implementation of IO in Layers pod/perlipc.pod Perl interprocess communication @@ -4357,12 +4361,12 @@ pod/perlref.pod Perl references, the rest of the story pod/perlreftut.pod Perl references short introduction pod/perlreguts.pod Perl regular expression engine internals pod/perlre.pod Perl regular expressions, the rest of the story -pod/perlrepository.pod Perl source repository pod/perlrequick.pod Perl regular expressions quick start pod/perlreref.pod Perl regular expressions quick reference pod/perlretut.pod Perl regular expressions tutorial pod/perlrun.pod Perl execution and options pod/perlsec.pod Perl security +pod/perlsource.pod Guide to the Perl source tree pod/perlstyle.pod Perl style guide pod/perlsub.pod Perl subroutines pod/perlsyn.pod Perl syntax diff --git a/pod.lst b/pod.lst index 5c5ecc1..76be8e3 100644 --- a/pod.lst +++ b/pod.lst @@ -124,8 +124,12 @@ g perlintern Perl internal functions (autogenerated) perlapio Perl internal IO abstraction interface perlhack Perl hackers guide + perlsource Guide to the Perl source tree + perlinterp Overview of the Perl intepreter source and how it works + perlhacktut Walk through the creation of a simple C code patch + perlhacktips Tips for Perl core C code hacking perlpolicy Perl development policies - perlrepository Perl source repository + perlgit Using git with the Perl repository h Miscellaneous diff --git a/pod/perl.pod b/pod/perl.pod index aeaa1ca..06de47e 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -145,8 +145,12 @@ For ease of access, the Perl manual has been split up into several sections. perlapio Perl internal IO abstraction interface perlhack Perl hackers guide + perlsource Guide to the Perl source tree + perlinterp Overview of the Perl intepreter source and how it works + perlhacktut Walk through the creation of a simple C code patch + perlhacktips Tips for Perl core C code hacking perlpolicy Perl development policies - perlrepository Perl source repository + perlgit Using git with the Perl repository =head2 Miscellaneous diff --git a/pod/perldelta.pod b/pod/perldelta.pod index b52960a..f85e5e2 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -192,13 +192,24 @@ XXX Changes which significantly change existing files in F go here. However, any changes to F should go in the L section. -=head3 L +=head3 L and perlrepository =over 4 =item * -XXX Description of the change here +The L and perlrepository documents have been heavily edited and +split up into several new documents. + +The L document is now much shorter, and focuses on the Perl 5 +development process and submitting patches to Perl. The technical content has +been moved to several new documents, L, L, +L, and L. This technical content has only been +lightly edited. + +The perlrepository document has been renamed to L. This new document +is just a how-to on using git with the Perl source code. Any other content +that used to be in perlrepository has been moved to perlhack. =back diff --git a/pod/perlrepository.pod b/pod/perlgit.pod similarity index 62% rename from pod/perlrepository.pod rename to pod/perlgit.pod index 350b128..ccc7c2c 100644 --- a/pod/perlrepository.pod +++ b/pod/perlgit.pod @@ -2,130 +2,40 @@ =for comment Consistent formatting of this file is achieved with: - perl ./Porting/podtidy pod/perlrepository.pod + perl ./Porting/podtidy pod/perlgit.pod =head1 NAME -perlrepository - Using the Perl source repository +perlgit - Detailed information about git and the Perl repository -=head1 SYNOPSIS +=head1 DESCRIPTION -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 version control -system we were using previously. This repository is accessible in -different ways. - -The full repository takes up about 80MB of disk space. A check out of -the blead branch (that is, the main development branch, which contains -bleadperl, the development version of perl 5) takes up about 160MB of -disk space (including the repository). A build of bleadperl takes up -about 200MB (including the repository and the check out). - -=head1 Getting access to the repository - -=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: - - http://perl5.git.perl.org/perl.git - -A mirror of the repository is found at: - - http://github.com/mirrors/perl - -=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 (which uses port 9418): - - % git clone git://perl5.git.perl.org/perl.git perl-git - -This clones the repository and makes a local copy in the F -directory. - -If your local network does not allow you to use port 9418, then you can -fetch a copy of the repository over HTTP (this is at least 4x slower): - - % git clone http://perl5.git.perl.org/perl.git perl-http - -This clones the repository and makes a local copy in the F -directory. - -=head2 Write access to the repository - -If you are a committer, then you can fetch a copy of the repository -that you can push back on with: - - % git clone ssh://perl5.git.perl.org/perl.git perl-ssh - -This clones the repository and makes a local copy in the F -directory. - -If you cloned using the git protocol, which is faster than ssh, then -you will need to modify the URL for the origin remote to enable -pushing. To do that edit F<.git/config> with git-config(1) like this: - - % git config remote.origin.url ssh://perl5.git.perl.org/perl.git - -You can also set up your user name and e-mail address. Most people do -this once globally in their F<~/.gitconfig> by doing something like: - - % git config --global user.name "Ævar Arnfjörð Bjarmason" - % git config --global user.email avarab@gmail.com - -However if you'd like to override that just for perl then execute then -execute something like the following in F: - - % git config user.email avar@cpan.org +This document provides details on using git to develop Perl. If you are +just interested in working on a quick patch, see L first. +This document is intended for people who are regular contributors to +Perl, including those with write access to the git repository. -It is also possible to keep C as a git remote, and add a new -remote for ssh access: +=head1 CLONING THE REPOSITORY - % git remote add camel perl5.git.perl.org:/perl.git +All of Perl's source code is kept centrally in a Git repository at +I. -This allows you to update your local repository by pulling from -C, which is faster and doesn't require you to authenticate, and -to push your changes back with the C remote: +You can make a read-only clone of the repository by running: - % git fetch camel - % git push camel + % git clone git://perl5.git.perl.org/perl.git perl -The C command just updates the C refs, as the objects -themselves should have been fetched when pulling from C. +This uses the git protocol (port 9418). -=head2 A note on camel and dromedary +If you cannot use the git protocol for firewall reasons, you can also +clone via http, though this is much slower: -The committers have SSH access to the two servers that serve -C. One is C itself (I), -which is the 'master' repository. The second one is -C (I), which can be used for -general testing and development. Dromedary syncs the git tree from -camel every few minutes, you should not push there. Both machines also -have a full CPAN mirror in /srv/CPAN, please use this. To share files -with the general public, dromedary serves your ~/public_html/ as -C + % git clone http://perl5.git.perl.org/perl.git perl -These hosts have fairly strict firewalls to the outside. Outgoing, only -rsync, ssh and git are allowed. For http and ftp, you can use -http://webproxy:3128 as proxy. Incoming, the firewall tries to detect -attacks and blocks IP addresses with suspicious activity. This -sometimes (but very rarely) has false positives and you might get -blocked. The quickest way to get unblocked is to notify the admins. - -These two boxes are owned, hosted, and operated by booking.com. You can -reach the sysadmins in #p5p on irc.perl.org or via mail to -C - -=head1 Overview of the repository +=head1 WORKING WITH THE REPOSITORY Once you have changed into the repository directory, you can inspect -it. - -After a clone the repository will contain a single local branch, which -will be the current branch as well, as indicated by the asterisk. +it. After a clone the repository will contain a single local branch, +which will be the current branch as well, as indicated by the asterisk. % git branch * blead @@ -204,12 +114,12 @@ how to change things. For instance the following: # Changes to be committed: # (use "git reset HEAD ..." to unstage) # - # modified: pod/perlrepository.pod + # modified: pod/perlgit.pod # # Changed but not updated: # (use "git add ..." to update what will be committed) # - # modified: pod/perlrepository.pod + # modified: pod/perlgit.pod # # Untracked files: # (use "git add ..." to include in what will be committed) @@ -225,65 +135,20 @@ not been pushed to the C remote yet. B: that this output is also what you see as a template if you do not provide a message to C. -Assuming that you'd like to commit all the changes you've just made as -a a single atomic unit, run this command: - - % git commit -a - -(That C<-a> tells git to add every file you've changed to this commit. -New files aren't automatically added to your commit when you use -C If you want to add files or to commit some, but not all of -your changes, have a look at the documentation for C.) - -Git will start up your favorite text editor, so that you can craft a -commit message for your change. See L below for more -information about what makes a good commit message. - -Once you've finished writing your commit message and exited your -editor, git will write your change to disk and tell you something like -this: +=head2 Patch workflow - Created commit daf8e63: explain git status and stuff about remotes - 1 files changed, 83 insertions(+), 3 deletions(-) - - -If you re-run C, you should see something like this: - - % git status - # On branch blead - # Your branch is ahead of 'origin/blead' by 2 commits. - # - # Untracked files: - # (use "git add ..." to include in what will be committed) - # - # deliberate.untracked - nothing added to commit but untracked files present (use "git add" to track) +First, please read L for details on hacking the Perl core. +That document covers many details on how to create a good patch. - -When in doubt, before you do anything else, check your status and read -it carefully, many questions are answered directly by the git status -output. - -=head1 Submitting a patch - -If you have a patch in mind for Perl, you should first get a copy of -the repository: - - % git clone git://perl5.git.perl.org/perl.git perl-git - -Then change into the directory: - - % cd perl-git - -Alternatively, if you already have a Perl repository, you should ensure -that you're on the I branch, and your repository is up to date: +If you already have a Perl repository, you should ensure that you're on +the I branch, and your repository is up to date: % git checkout blead % git pull It's preferable to patch against the latest blead version, since this is where new development occurs for all changes other than critical bug -fixes. Critical bug fix patches should be made against the relevant +fixes. Critical bug fix patches should be made against the relevant maint branches, or should be submitted with a note indicating all the branches where the fix should be applied. @@ -336,68 +201,48 @@ And you can see the changes: Lesley Binks Lincoln D. Stein -For changes significant enough to warrant a F entry, the -porters would greatly appreciate it if you submit an 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 +Now commit your change locally: -=item * + % git commit -a -m 'Rename Leon Brocard to Orange Brocard' + Created commit 6196c1d: Rename Leon Brocard to Orange Brocard + 1 files changed, 1 insertions(+), 1 deletions(-) -important platform-specific changes +The C<-a> option is used to include all files that git tracks that you +have changed. If at this time, you only want to commit some of the +files you have worked on, you can omit the C<-a> and use the command +C>> before doing the commit. C> allows you to even just commit portions of files +instead of all the changes in them. -=back +The C<-m> option is used to specify the commit message. If you omit it, +git will open a text editor for you to compose the message +interactively. This is useful when the changes are more complex than +the sample given here, and, depending on the editor, to know that the +first line of the commit message doesn't exceed the 50 character legal +maximum. -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