X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrepository.pod;h=ec0294a0f21263ff7d33dfea9e9b8c521d4abc62;hb=18fd877aa5c85a3f8bdc7cb30b117cf8f0fe97a6;hp=b766cee193a6d9e5685500f2ee294b2d3d3f9d28;hpb=03050721b3bc3f299369ca775c64ffaf12c3508e;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index b766cee..ec0294a 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -8,27 +8,32 @@ 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 -the blead branch (that is, the master 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). +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 @@ -57,9 +62,9 @@ that you can push back on with: 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 F<.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 @@ -69,8 +74,9 @@ 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. You can also set up your user name and e-mail address. For example @@ -80,7 +86,7 @@ You can also set up your user name and e-mail address. For example It is also possible to keep C as a git remote, and add a new remote for ssh access: - % git remote add camel user@camel:/gitroot/perl.git + % git remote add camel perl5.git.perl.org:/perl.git This allows you to update your local repository by pulling from C, which is faster and doesn't require you to authenticate, and @@ -92,6 +98,15 @@ to push your changes back with the C remote: 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 @@ -242,10 +257,11 @@ 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 -patches are usually integrated from blead to the maintenance branches. -This does not apply, obviously, in the rare case where your patch is -specific to a maintaince release.) +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: @@ -291,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: @@ -326,24 +350,9 @@ $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. -=head2 A note on binary files - -Since the patch(1) utility cannot deal with binary files, it's -important that you either avoid the use of binary files in your patch, -generate the files dynamically, or that you encode any binary files -using the F utility. +=for XXX -Assuming you needed to include a gzip-encoded file for a module's test -suite, you might do this as follows using the F utility: - - $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz - Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed - -This will replace the C file with an encoded counterpart. During -C, before any tests are run, perl's Makefile will restore -all the C<.packed> files mentioned in the MANIFEST to their original -name. This means that the test suite does not need to be aware of this -packing scheme and will not need to be altered. +What should we recommend about binary files now? Do we need anything? =head2 Getting your patch accepted @@ -446,19 +455,17 @@ If just a raw diff is provided, it is also possible use this two-step process: % git apply bugfix.diff - % git commit -am "Some fixing" --author="That Guy " + % 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 @@ -492,7 +499,7 @@ If you want to delete your temporary branch, you may do so with: =head1 CLEANING A WORKING DIRECTORY The command C can with varying arguments be used as a -replacement for make-clean. +replacement for C. To reset your working directory to a pristine condition you can do: @@ -506,7 +513,8 @@ 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. +checkout> 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. @@ -524,9 +532,17 @@ testcase: #!/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" || exit 125 - make || exit 125 + 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 @@ -596,8 +612,7 @@ We shall make the same patch as above, creating a new branch: % git pull upstream blead % git checkout -b orange % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS - % git add AUTHORS - % git commit -m 'Rename Leon Brocard to Orange Brocard' + % 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 @@ -607,8 +622,38 @@ 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: