X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlrepository.pod;h=ec0294a0f21263ff7d33dfea9e9b8c521d4abc62;hb=18fd877aa5c85a3f8bdc7cb30b117cf8f0fe97a6;hp=45f01dec2a5da58e94fd6023a676f46592eb5146;hpb=dc3c30404e1546ebc4bd89fa72dfcd44bcd246ee;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 45f01de..ec0294a 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -9,16 +9,16 @@ perlrepository - Using the Perl source repository =head1 SYNOPSIS 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. +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 @@ -62,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 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: +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 @@ -98,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 @@ -248,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: @@ -306,8 +316,7 @@ 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: +itself you can fix it up by editing the files once more and then issue: % git commit -a --amend @@ -341,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. - -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: +=for XXX - $ 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 @@ -519,8 +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, or C to revert them all. +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. @@ -538,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 @@ -620,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: