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
+ git clone ssh://perl5.git.perl.org/perl.git perl-ssh
This clones the repository and makes a local copy in the F<perl-ssh>
directory.
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 optional and
-since SSH is the default protocol you can actually shorten the "url" to
-C<perl5.git.perl.org:/perl.git>.
+ url = ssh://perl5.git.perl.org/perl.git
You can also set up your user name and e-mail address. For example
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
+=head2 A NOTE ON CAMEL AND DROMEDARY
+
+The committers have SSH access to the two servers that serve
C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>),
which is the 'master' repository. The second one is
C<users.perl5.git.perl.org> (I<dromedary>), 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
+have a full CPAN mirror in /srv/CPAN, please use this. To share files
+with the general public, dromedary serves your ~/public_html/ as
C<http://users.perl5.git.perl.org/~yourlogin/>
+These hosts have fairly strict firewalls to the outside. Outgoing, only
+rsync, ssh and git are allowed. For http and ftp, you can use
+http://webproxy:3128 as proxy. Incoming, the firewall tries to detect
+attacks and blocks IP addresses with suspicious activity. This
+sometimes (but very rarely) has false positives and you might get
+blocked. The quickest way to get unblocked is to notify the admins.
+
+These two boxes are owned, hosted, and operated by booking.com. You can
+reach the sysadmins in #p5p on irc.perl.org or via mail to
+C<perl5-porters@perl.org>
+
=head1 OVERVIEW OF THE REPOSITORY
Once you have changed into the repository directory, you can inspect
is also what you see as a template if you do not provide a message to
C<git commit>.
-Assuming we commit all the mentioned changes above:
+Assuming that you'd like to commit all the changes you've just made as a
+a single atomic unit, run this command:
+
+ % git commit -a
+
+(That C<-a> tells git to add every file you've changed to this commit.
+If you want to commit some, but not all of your changes, have a look
+at the documentation for C<git add>.)
+
+Git will start up your favorite text editor, so that you can craft a
+commit message for your change. See L</Commit message> below for more
+information about what makes a good commit message.
+
+Once you've finished writing your commit message and exited your editor,
+git will write your change to disk and tell you something like this:
- % 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:
+
+If you re-run C<git status>, you should see something like this:
% git status
# On branch blead
file that may have gotten copied while building the source
distribution, consult the C<MANIFEST>.
+As a special case, several files are regenerated by 'make regen' if
+your patch alters C<embed.fnc>. These are needed for compilation, but
+are included in the distribution so that you can build perl without
+needing another perl to generate the files. You must test with these
+regenerated files, but it is preferred that you instead note that
+'make regen is needed' in both the email and the commit message, and
+submit your patch without them. If you're submitting a series of
+patches, it might be best to submit the regenerated changes
+immediately after the source-changes that caused them, so as to have
+as little effect as possible on the bisectability of your patchset.
+
=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
+If you are submitting a code patch there are several things that
you need to do.
=over 4
+=item Commit message
+
+As you craft each patch you intend to submit to the Perl core, it's
+important to write a good commit message.
+
+Your commit message should start with a description of the problem that
+the patch corrects or new functionality that the patch adds.
+
+As a general rule of thumb, your commit message should let a programmer
+with a reasonable familiarity with the Perl core quickly understand what
+you were trying to do, how you were trying to do it and why the change
+matters to Perl.
+
+=over 4
+
+=item What
+
+Your commit message should describe what part of the Perl core you're
+changing and what you expect your patch to do.
+
+=item Why
+
+Perhaps most importantly, your commit message should describe why the
+change you are making is important. When someone looks at your change
+in six months or six years, your intent should be clear. If you're
+deprecating a feature with the intent of later simplifying another bit
+of code, say so. If you're fixing a performance problem or adding a new
+feature to support some other bit of the core, mention that.
+
+=item How
+
+While it's not necessary for documentation changes, new tests or
+trivial patches, it's often worth explaining how your change works.
+Even if it's clear to you today, it may not be clear to a porter next
+month or next year.
+
+=back
+
=item Comments, Comments, Comments
Be sure to adequately comment your code. While commenting every line
=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.
+If your patch changes code (rather than just changing documentation) you
+should also include one or more test cases which illustrate the bug you're
+fixing or validate the new functionality you're adding. In general,
+you should update an existing test file rather than create a new one.
+
Your testsuite additions should generally follow these guidelines
(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
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
+when some behaviour is correct, and with C<1> when it's faulty. You need
an helper script that automates building C<perl> and running the
testcase:
#!/bin/sh
git clean -dxf
# If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
+ # if Encode is not needed for the test, you can speed up the bisect by
+ # excluding it from the runs with -Dnoextensions=Encode
sh Configure -des -Dusedevel -Doptimize="-g"
test -f config.sh || exit 125
# Correct makefile for newer GNU gcc
should be skipped. Otherwise, it returns the status of
F<~/testcase.pl>.
-We first enter in bisect mode with:
+You first enter in bisect mode with:
% git bisect start
Bisecting: 853 revisions left to test after this
This results in checking out the median commit between C<HEAD> and
-C<perl-5.10.0>. We can then run the bisecting process with:
+C<perl-5.10.0>. You can then run the bisecting process with:
% git bisect run ~/run
% git clone git@github.com:USERNAME/perl.git perl-github
-We shall make the same patch as above, creating a new branch:
+The same patch as above, using github might look like this:
% cd perl-github
% git remote add upstream git://github.com/github/perl.git
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>.
projects / p5sagit/p5-mst-13.2.git / blobdiff