X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrepository.pod;h=ec0294a0f21263ff7d33dfea9e9b8c521d4abc62;hb=18fd877aa5c85a3f8bdc7cb30b117cf8f0fe97a6;hp=05b1e1a933767775827ea52e98b5e4f16f1a324f;hpb=39219fd358d77b4ca3b647d1ee7ea114f08104d7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 05b1e1a..ec0294a 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -1,29 +1,39 @@ +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlrepository.pod + =head1 NAME perlrepository - Using the Perl source repository =head1 SYNOPSIS -All of Perl's source code is kept centrally in a Git repository. 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. +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 -blead takes up about 160MB of disk space (including the repository). A -build of blead takes up about 200MB (including the repository and the -check out). +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 this over the web. This allows you to browse the tree, -see recent commits, search for particular commits and more. You may -access it at: +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/github/perl + =head2 READ ACCESS VIA GIT You will need a copy of Git for your computer. You can fetch a copy of @@ -31,7 +41,7 @@ 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 '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 @@ -39,22 +49,22 @@ fetch a copy of the repository over HTTP (this is slower): git clone http://perl5.git.perl.org/perl.git perl-http -This clones the repository and makes a local copy in the '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: +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/gitroot/perl.git perl-ssh -This clones the repository and makes a local copy in the 'perl-ssh' +This clones the repository and makes a local copy in the F directory. -If you clone using git, which is faster than ssh, then you will need to -modify your config in order to enable pushing. Edit .git/config where -you will see something like: +If you cloned using the git protocol, which is faster than ssh, then +you will need to modify your config in order to enable pushing. Edit +F<.git/config> where you will see something like: [remote "origin"] url = git://perl5.git.perl.org/perl.git @@ -64,68 +74,105 @@ change that to something like this: [remote "origin"] url = ssh://perl5.git.perl.org/gitroot/perl.git -NOTE: there are symlinks set up so that the /gitroot is actually optional. +NOTE: there are symlinks set up so that the /gitroot is optional and +since SSH is the default protocol you can actually shorten the "url" to +C. -=head1 OVERVIEW OF THE REPOSITORY +You can also set up your user name and e-mail address. For example + + % git config user.name "Leon Brocard" + % git config user.email acme@astray.com + +It is also possible to keep C as a git remote, and add a new +remote for ssh access: + + % git remote add camel perl5.git.perl.org:/perl.git -Once you have changed into the repository directory, you can inspect it. +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: + % git fetch camel + % git push camel + +The C command just updates the C refs, as the objects +themselves should have been fetched when pulling from C. + +The committers have access to 2 servers that serve perl5.git.perl.org. +One is camel.booking.com, which is the 'master' repository. The +perl5.git.perl.org IP address also lives on this machine. The second +one is dromedary.booking.com, 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. +To share files with the general public, dromedary serves your +~/public_html/ as http://users.perl5.git.perl.org/~yourlogin/ + +=head1 OVERVIEW OF 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 asterix. +will be the current branch as well, as indicated by the asterisk. % git branch * blead -Using the -a switch to branch will show the remote tracking branches in the -repository: +Using the -a switch to C will also show the remote tracking +branches in the repository: - % git branch -r + % git branch -a * blead origin/HEAD origin/blead ... -The branches that begin with "origin" correspond to the "git remote" that -you cloned from. Each branch on the remote will be exactly tracked by theses -branches. You should NEVER do work on these remote tracking branches. You only -ever do work in a local branch. Local branches can be configured to automerge -(on pull) from a designated remote tracking branch. This is the case with the -default branch C which will be configured to merge from the remote -tracking branch C. +The branches that begin with "origin" correspond to the "git remote" +that you cloned from (which is named "origin"). Each branch on the +remote will be exactly tracked by theses branches. You should NEVER do +work on these remote tracking branches. You only ever do work in a +local branch. Local branches can be configured to automerge (on pull) +from a designated remote tracking branch. This is the case with the +default branch C which will be configured to merge from the +remote tracking branch C. You can see recent commits: % git log -And pull new changes from the repository, and update your local repository -(must be clean first) +And pull new changes from the repository, and update your local +repository (must be clean first) % git pull -Assuming we are on the branch C immediately after a pull, this command -would be more or less equivalent to: +Assuming we are on the branch C immediately after a pull, this +command would be more or less equivalent to: % git fetch % git merge origin/blead -In fact if you want to update your local repository without touching your working -directory you do: +In fact if you want to update your local repository without touching +your working directory you do: % git fetch -And if you want to update your remote tracking branches for all defined remotes -simultaneously you do +And if you want to update your remote-tracking branches for all defined +remotes simultaneously you can do % git remote update -Neither of these last two commands will update your working directory, however -both will update the repository. +Neither of these last two commands will update your working directory, +however both will update the remote-tracking branches in your +repository. To switch to another branch: % git checkout origin/maint-5.8-dor +To make a local branch of a remote branch: + + % git checkout -b maint-5.10 origin/maint-5.10 + To switch back to blead: % git checkout blead @@ -136,11 +183,11 @@ The most common git command you will use will probably be % git status -This command will produce as output a description of the current state of the -repository, including modified files and unignored untracked files, and in addition -it will show things like what files have been staged for the next commit, -and usually some useful information about how to change things. For instance the -following: +This command will produce as output a description of the current state +of the repository, including modified files and unignored untracked +files, and in addition it will show things like what files have been +staged for the next commit, and usually some useful information about +how to change things. For instance the following: $ git status # On branch blead @@ -161,18 +208,37 @@ following: # # deliberate.untracked -This shows that there were changes to this document staged for commit, and -that there were further changes in the working directory not yet staged. It -also shows that there was an untracked file in the working directory, and as -you can see shows how to change all of this. It also shows that there -is one commit on the working branch C which has not been pushed to the -C remote yet. +This shows that there were changes to this document staged for commit, +and that there were further changes in the working directory not yet +staged. It also shows that there was an untracked file in the working +directory, and as you can see shows how to change all of this. It also +shows that there is one commit on the working branch C which has +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 we commit all the mentioned changes above: + + % git commit -a -m'explain git status and stuff about remotes' + Created commit daf8e63: explain git status and stuff about remotes + 1 files changed, 83 insertions(+), 3 deletions(-) + +We can re-run git status and 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) -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. -NOTE: that this output is also what you see as a template if you do not -provide a message to c. +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 @@ -185,18 +251,23 @@ 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: +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: % git checkout blead % git pull -Now that we have everything up to date, we need to create a temporary new -branch for these changes and switch into it: +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 +maint branches, or should be submitted with a note indicating all the +branches where the fix should be applied. + +Now that we have everything up to date, we need to create a temporary +new branch for these changes and switch into it: % git checkout -b orange - + which is the short form of % git branch orange @@ -210,7 +281,7 @@ to Orange Brocard, we should change his name in the AUTHORS file: You can see what files are changed: % git status - # On branch blead + # On branch orange # Changes to be committed: # (use "git reset HEAD ..." to unstage) # @@ -236,18 +307,26 @@ And you can see the changes: Now commit your change locally: - % git add AUTHORS - % git commit -m 'Rename Leon Brocard to Orange Brocard' + % 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(-) +You can examine your last commit with: + + % git show HEAD + +and if you are not happy with either the description or the patch +itself you can fix it up by editing the files once more and then issue: + + % git commit -a --amend + Now you should create a patch file for all your local changes: % git format-patch origin 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch You should now send an email to perl5-porters@perl.org with a -description of your changes, and attach this patch file as an +description of your changes, and include this patch file as an attachment. If you want to delete your temporary branch, you may do so with: @@ -259,6 +338,103 @@ If you want to delete your temporary branch, you may do so with: % git branch -D orange Deleted branch orange. +=head2 A note on derived files + +Be aware that many files in the distribution are derivative--avoid +patching them, because git won't see the changes to them, and the build +process will overwrite them. Patch the originals instead. Most +utilities (like perldoc) are in this category, i.e. patch +utils/perldoc.PL rather than utils/perldoc. Similarly, don't create +patches for files under $src_root/ext from their copies found in +$install_root/lib. If you are unsure about the proper location of a +file that may have gotten copied while building the source +distribution, consult the C. + +=for XXX + +What should we recommend about binary files now? Do we need anything? + +=head2 Getting your patch accepted + +The first thing you should include with your patch is a description of +the problem that the patch corrects. If it is a code patch (rather +than a documentation patch) you should also include a small test case +that illustrates the bug (a patch to an existing test file is +preferred). + +If you are submitting a code patch there are several other things that +you need to do. + +=over 4 + +=item 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. + +=item Style + +In general, please follow the particular style of the code you are +patching. + +In particular, follow these general guidelines for patching Perl +sources: + + 8-wide tabs (no exceptions!) + 4-wide indents for code, 2-wide indents for nested CPP #defines + try hard not to exceed 79-columns + ANSI C prototypes + uncuddled elses and "K&R" style for indenting control constructs + no C++ style (//) comments + mark places that need to be revisited with XXX (and revisit often!) + opening brace lines up with "if" when conditional spans multiple + lines; should be at end-of-line otherwise + in function definitions, name starts in column 0 (return value is on + previous line) + single space after keywords that are followed by parens, no space + between function name and following paren + avoid assignments in conditionals, but if they're unavoidable, use + extra paren, e.g. "if (a && (b = c)) ..." + "return foo;" rather than "return(foo);" + "if (!foo) ..." rather than "if (foo == FALSE) ..." etc. + +=item Testsuite + +When submitting a patch you should make every effort to also include an +addition to perl's regression tests to properly exercise your patch. +Your testsuite additions should generally follow these guidelines +(courtesy of Gurusamy Sarathy ): + + Know what you're testing. Read the docs, and the source. + Tend to fail, not succeed. + Interpret results strictly. + Use unrelated features (this will flush out bizarre interactions). + Use non-standard idioms (otherwise you are not testing TIMTOWTDI). + 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). + Give meaningful error messages when a test fails. + Avoid using qx// and system() unless you are testing for them. If you + do use them, make sure that you cover _all_ perl platforms. + Unlink any temporary files you create. + Promote unforeseen warnings to errors with $SIG{__WARN__}. + Be sure to use the libraries and modules shipped with the version + being tested, not those that were already installed. + Add comments to the code explaining what you are testing for. + Make updating the '1..42' string unnecessary. Or make sure that + you update it. + Test _all_ behaviors of a given operator, library, or function: + - All optional arguments + - Return values in various contexts (boolean, scalar, list, lvalue) + - Use both global and lexical variables + - Don't forget the exceptional, pathological cases. + +=back + =head1 ACCEPTING A PATCH If you have received a patch file generated using the above section, @@ -269,22 +445,27 @@ switch into it: % git checkout -b experimental -Now we should apply the patch: +Patches that were formatted by C are applied with +C: % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch Applying Rename Leon Brocard to Orange Brocard +If just a raw diff is provided, it is also possible use this two-step +process: + + % git apply bugfix.diff + % git commit -a -m "Some fixing" --author="That Guy " + Now we can inspect the change: - % git log + % git show HEAD commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 Author: Leon Brocard Date: Fri Dec 19 17:02:59 2008 +0000 Rename Leon Brocard to Orange Brocard - ... - % git diff blead diff --git a/AUTHORS b/AUTHORS index 293dd70..722c93e 100644 --- a/AUTHORS @@ -303,7 +484,7 @@ If you are a committer to Perl and you think the patch is good, you can then merge it into blead then push it out to the main repository: % git checkout blead - % git pull . experimental + % git merge experimental % git push If you want to delete your temporary branch, you may do so with: @@ -314,3 +495,180 @@ If you want to delete your temporary branch, you may do so with: If you are sure you want to delete it, run 'git branch -D experimental'. % git branch -D experimental Deleted branch experimental. + +=head1 CLEANING A WORKING DIRECTORY + +The command C can with varying arguments be used as a +replacement for C. + +To reset your working directory to a pristine condition you can do: + + git clean -dxf + +However, be aware this will delete ALL untracked content. You can use + + git clean -Xf + +to remove all ignored untracked files, such as build and test +byproduct, but leave any manually created files alone. + +If you only want to cancel some uncommitted edits, you can use C and give it a list of files to be reverted, or C to revert them all. + +If you want to cancel one or several commits, you can use C. + +=head1 BISECTING + +C provides a built-in way to determine, with a binary search in +the history, which commit should be blamed for introducing a given bug. + +Suppose that we have a script F<~/testcase.pl> that exits with C<0> +when some behaviour is correct, and with C<1> when it's faulty. We need +an helper script that automates building C and running the +testcase: + + % cat ~/run + #!/bin/sh + git clean -dxf + # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line + sh Configure -des -Dusedevel -Doptimize="-g" + test -f config.sh || exit 125 + # Correct makefile for newer GNU gcc + perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile + # if you just need miniperl, replace test_prep with miniperl + make -j4 test_prep + -x ./perl || exit 125 + ./perl -Ilib ~/testcase.pl + ret=$? + git clean -dxf + exit $ret + +This script may return C<125> to indicate that the corresponding commit +should be skipped. Otherwise, it returns the status of +F<~/testcase.pl>. + +We first enter in bisect mode with: + + % git bisect start + +For example, if the bug is present on C but wasn't in 5.10.0, +C will learn about this when you enter: + + % git bisect bad + % git bisect good perl-5.10.0 + Bisecting: 853 revisions left to test after this + +This results in checking out the median commit between C and +C. We can then run the bisecting process with: + + % git bisect run ~/run + +When the first bad commit is isolated, C will tell you so: + + ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit + commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 + Author: Dave Mitchell + Date: Sat Feb 9 14:56:23 2008 +0000 + + [perl #49472] Attributes + Unknown Error + ... + + bisect run success + +You can peek into the bisecting process with C and +C. C will get you out of bisect +mode. + +Please note that the first C state must be an ancestor of the +first C state. If you want to search for the commit that I +some bug, you have to negate your test case (i.e. exit with C<1> if OK +and C<0> if not) and still mark the lower bound as C and the +upper as C. The "first bad commit" has then to be understood as +the "first commit where the bug is solved". + +C has much more information on how you can tweak your +binary searches. + +=head1 SUBMITTING A PATCH VIA GITHUB + +GitHub is a website that makes it easy to fork and publish projects +with Git. First you should set up a GitHub account and log in. + +Perl's git repository is mirrored on GitHub at this page: + + http://github.com/github/perl/tree/blead + +Visit the page and click the "fork" button. This clones the Perl git +repository for you and provides you with "Your Clone URL" from which +you should clone: + + % git clone git@github.com:USERNAME/perl.git perl-github + +We shall make the same patch as above, creating a new branch: + + % cd perl-github + % git remote add upstream git://github.com/github/perl.git + % git pull upstream blead + % git checkout -b orange + % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS + % git commit -a -m 'Rename Leon Brocard to Orange Brocard' + % git push origin orange + +The orange branch has been pushed to GitHub, so you should now send an +email to perl5-porters@perl.org with a description of your changes and +the following information: + + http://github.com/USERNAME/perl/tree/orange + git@github.com:USERNAME/perl.git branch orange + +=head1 MERGING FROM A BRANCH VIA GITHUB + +If someone has provided a branch via GitHub and you are a committer, +you should use the following in your perl-ssh directory: + + % git remote add dandv git://github.com/dandv/perl.git + % git fetch + +Now you can see the differences between the branch and blead: + + % git diff dandv/blead + +And you can see the commits: + + % git log dandv/blead + +If you approve of a specific commit, you can cherry pick it: + + % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f + +Or you could just merge the whole branch if you like it all: + + % git merge dandv/blead + +And then push back to the repository: + + % git push + +=head1 COMMITTING TO MAINTENANCE VERSIONS + +Maintenance versions should only be altered to add critical bug fixes. + +To commit to a maintenance version of perl, you need to create a local +tracking branch: + + % git checkout --track -b maint-5.005 origin/maint-5.005 + +This creates a local branch named C, which tracks the +remote branch C. Then you can pull, commit, merge +and push as before. + +You can also cherry-pick commits from blead and another branch, by +using the C command. It is recommended to use the +B<-x> option to C in order to record the SHA1 of the +original commit in the new commit message. + +=head1 SEE ALSO + +The git documentation, accessible via C. +