=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<perl5.git.perl.org>. 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
This clones the repository and makes a local copy in the F<perl-ssh>
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
[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<perl5.git.perl.org:/perl.git>.
You can also set up your user name and e-mail address. For example
It is also possible to keep C<origin> 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<origin>, which is faster and doesn't require you to authenticate, and
The C<fetch> command just updates the C<camel> refs, as the objects
themselves should have been fetched when pulling from C<origin>.
+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
% 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:
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:
file that may have gotten copied while building the source
distribution, consult the C<MANIFEST>.
-=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<uupacktool.pl> 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<uupacktool.pl> 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<t.gz> file with an encoded counterpart. During
-C<make test>, 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
process:
% git apply bugfix.diff
- % git commit -am "Some fixing" --author="That Guy <that.guy@internets.com>"
+ % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>"
Now we can inspect the change:
- % git log
+ % git show HEAD
commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
Author: Leon Brocard <acme@astray.com>
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
=head1 CLEANING A WORKING DIRECTORY
The command C<git clean> can with varying arguments be used as a
-replacement for make-clean.
+replacement for C<make clean>.
To reset your working directory to a pristine condition you can do:
byproduct, but leave any manually created files alone.
If you only want to cancel some uncommitted edits, you can use C<git
-checkout> and give it a list of files to be reverted.
+checkout> and give it a list of files to be reverted, or C<git checkout
+-f> to revert them all.
If you want to cancel one or several commits, you can use C<git reset>.
#!/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
% 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
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:
projects / p5sagit/p5-mst-13.2.git / blobdiff