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
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:
You should now send an email to perl5-porters@perl.org with a
description of your changes, and include this patch file as an
-attachment.
+attachment. (See the next section for how to configure and use
+git to send these emails for you.)
If you want to delete your temporary branch, you may do so with:
% git branch -D orange
Deleted branch orange.
+=head2 Using git to send patch emails
+
+In your ~/git/perl repository, set the destination email to the perl5-porters
+mailing list.
+
+ $ git config sendemail.to perl5-porters@perl.org
+
+Then you can use git directly to send your patch emails:
+
+ $ git send-email 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
+
+You may need to set some configuration variables for your particular email
+service provider. For example, to set your global git config to send email via
+a gmail account:
+
+ $ git config --global sendemail.smtpserver smtp.gmail.com
+ $ git config --global sendemail.smtpssl 1
+ $ git config --global sendemail.smtpuser YOURUSERNAME@gmail.com
+
+With this configuration, you will be prompted for your gmail password when you
+run 'git send-email'. You can also configure C<sendemail.smtppass> with your
+password if you don't care about having your password in the .gitconfig file.
+
=head2 A note on derived files
Be aware that many files in the distribution are derivative--avoid
file that may have gotten copied while building the source
distribution, consult the C<MANIFEST>.
-=head2 A note on binary files
+=for XXX
-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.
-
-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
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
+ [ -x ./perl ] || exit 125
./perl -Ilib ~/testcase.pl
ret=$?
+ [ $ret -gt 127 ] && ret=127
git clean -dxf
exit $ret
=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:
B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
original commit in the new commit message.
+=head1 GRAFTS
+
+The perl history contains one mistake which was not caught in the
+conversion -- a merge was recorded in the history between blead and
+maint-5.10 where no merge actually occurred. Due to the nature of
+git, this is now impossible to fix in the public repository. You can
+remove this mis-merge locally by adding the following line to your
+C<.git/info/grafts> file:
+
+ 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
+
+It is particularly important to have this graft line if any bisecting
+is done in the area of the "merge" in question.
+
=head1 SEE ALSO
The git documentation, accessible via C<git help command>.