In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/705c800cbe8195e3d1d754695fccdb60a9e4d7d2?hp=83aa740ef4e0ec94b144304b034baf00e5d12723>
- Log ----------------------------------------------------------------- commit 705c800cbe8195e3d1d754695fccdb60a9e4d7d2 Author: Rafael Garcia-Suarez <[email protected]> Date: Fri Apr 23 14:45:09 2010 +0200 Pod formatting nits M pod/perlrepository.pod commit d080235a2c2e4003db36fa3f8f1bee8864dec607 Merge: 83aa740 fb60e74 Author: Rafael Garcia-Suarez <[email protected]> Date: Fri Apr 23 14:43:55 2010 +0200 Merge commit 'avar/avar/pod-perlrepository' into blead commit fb60e745fdab6c3df3d254b4c2a6939307d3f8a7 Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 19:28:01 2010 +0000 Don't ask the porters to fetch commits from a private URL [email protected]:USERNAME/perl.git is only accessible to USERNAME (or collaborators), git://github.com/USERNAME/perl.git is available to everyone. M pod/perlrepository.pod commit e98adcab11bec9a0f9fc869205a4d0fb0bafab68 Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 19:14:24 2010 +0000 Consistently use a topic branch in the GitHub examples Also use an example of an actual topic branch commit of that got into Perl (<[email protected]>). Previously the docs referenced 3adac458cb which doesn't exist in the repository, 0c24b290ae does. M pod/perlrepository.pod commit f15b1f22fda04a7eca534d4611fefda0b4e3547a Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 18:58:31 2010 +0000 Recommend git format-patch -M (detect renames) and origin.. The latter doesn't strictly matter, but it's easier to see what's going on with those two dots. M pod/perlrepository.pod commit 041325d6ab68691bb4a8d5f96eb3e1a196dd8598 Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 18:55:04 2010 +0000 Mention L<perlpolicy> and link to it in SEE ALSO M pod/perlrepository.pod commit ba336be1bea3ce6a079a831a7a58533d4e92ecc9 Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 18:50:42 2010 +0000 Only all-upper case "special" POD sections "GETTING ACCESS TO THE REPOSITORY" is a bit too loud compared to "Getting access to the repository". The POD standard itself doesn't have anything to say about this, but most of our long =head1 sections in pod/*.pod don't use all-caps. M pod/perlrepository.pod commit 1a5f98ea6257ef63e515f48e05311fba2cdd7dbc Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 18:36:51 2010 +0000 Commit messages should start with a ~50 char summary The first sentence is stolen from Git's own Documentation/SubmittingPatches. We have a lot of commit messages that overflow `git log --pretty=oneline', but it wouldn't hurt if we change that sooner rather than later. M pod/perlrepository.pod commit 0be741b53900848403d51758327b066a4784699c Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 18:32:45 2010 +0000 POD: Use F<> for F<utils/perldoc> and F<utils/perldoc.PL> M pod/perlrepository.pod commit 6053d6bc11958e181df09a1ea3fe94201e2c2896 Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 18:04:30 2010 +0000 Don't tell the reader to `git checkout origin/*' This results in a branchless checkout (detached HEAD). Making changes like this is a valid way to use Git, but IMO not something we should be recommending. Branches are cheap and it's harder to lose your commits if they're on a named branch than on a detached HEAD. M pod/perlrepository.pod commit 45b194c55901890d782546bf70eee5b9b5451083 Author: Ãvar Arnfjörð Bjarmason <[email protected]> Date: Tue Apr 20 17:50:03 2010 +0000 GitHub's mirror is now at mirrors/perl, not github/perl M pod/perlrepository.pod ----------------------------------------------------------------------- Summary of changes: pod/perlrepository.pod | 90 +++++++++++++++++++++++++++-------------------- 1 files changed, 52 insertions(+), 38 deletions(-) diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index eb748df..d79dc59 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -20,9 +20,9 @@ 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 +=head1 Getting access to the repository -=head2 READ ACCESS VIA THE WEB +=head2 Read access via the web 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, @@ -32,9 +32,9 @@ search for particular commits and more. You may access it at: A mirror of the repository is found at: - http://github.com/github/perl + http://github.com/mirrors/perl -=head2 READ ACCESS VIA GIT +=head2 Read access via Git You will need a copy of Git for your computer. You can fetch a copy of the repository using the Git protocol (which uses port 9418): @@ -52,7 +52,7 @@ fetch a copy of the repository over HTTP (this is at least 4x slower): This clones the repository and makes a local copy in the F<perl-http> directory. -=head2 WRITE ACCESS TO THE REPOSITORY +=head2 Write access to the repository If you are a committer, then you can fetch a copy of the repository that you can push back on with: @@ -64,7 +64,7 @@ directory. If you cloned using the git protocol, which is faster than ssh, then you will need to modify the URL for the origin remote to enable -pushing. To do that edit F<.git/config> with L<git-config(1)> like +pushing. To do that edit F<.git/config> with git-config(1) like this: % git config remote.origin.url ssh://perl5.git.perl.org/perl.git @@ -95,7 +95,7 @@ to push your changes back with the C<camel> remote: The C<fetch> command just updates the C<camel> refs, as the objects themselves should have been fetched when pulling from C<origin>. -=head2 A NOTE ON CAMEL AND DROMEDARY +=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>), @@ -118,7 +118,7 @@ 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<[email protected]> -=head1 OVERVIEW OF THE REPOSITORY +=head1 Overview of the repository Once you have changed into the repository directory, you can inspect it. @@ -176,10 +176,6 @@ Neither of these last two commands will update your working directory, however both will update the remote-tracking branches in your repository. -To switch to another branch: - - % git checkout origin/maint-5.8-dor - To make a local branch of a remote branch: % git checkout -b maint-5.10 origin/maint-5.10 @@ -188,7 +184,7 @@ To switch back to blead: % git checkout blead -=head2 FINDING OUT YOUR STATUS +=head2 Finding out your status The most common git command you will use will probably be @@ -266,7 +262,7 @@ When in doubt, before you do anything else, check your status and read it carefully, many questions are answered directly by the git status output. -=head1 SUBMITTING A PATCH +=head1 Submitting a patch If you have a patch in mind for Perl, you should first get a copy of the repository: @@ -356,7 +352,7 @@ itself you can fix it up by editing the files once more and then issue: Now you should create a patch file for all your local changes: - % git format-patch origin + % git format-patch -M origin.. 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch You should now send an email to either [email protected] or @@ -410,7 +406,7 @@ Be aware that many files in the distribution are derivative--avoid patching them, because git won't see the changes to them, and the build process will overwrite them. Patch the originals instead. Most utilities (like perldoc) are in this category, i.e. patch -utils/perldoc.PL rather than utils/perldoc. Similarly, don't create +F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't create patches for files under $src_root/ext from their copies found in $install_root/lib. If you are unsure about the proper location of a file that may have gotten copied while building the source @@ -443,8 +439,16 @@ you need to do. 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. +The first line of the commit message should be a short description and +should skip the full stop. It should be no longer than the subject +line of an E-Mail, 50 characters being a good rule of thumb. + +A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..) will +only display the first line (cut off at 50 characters) when presenting +commit summaries. + +The commit message should include 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 @@ -556,7 +560,7 @@ Your testsuite additions should generally follow these guidelines =back -=head1 ACCEPTING A PATCH +=head1 Accepting a patch If you have received a patch file generated using the above section, you should try out the patch. @@ -617,7 +621,7 @@ If you want to delete your temporary branch, you may do so with: % git branch -D experimental Deleted branch experimental. -=head1 CLEANING A WORKING DIRECTORY +=head1 Cleaning a working directory The command C<git clean> can with varying arguments be used as a replacement for C<make clean>. @@ -639,7 +643,7 @@ checkout> and give it a list of files to be reverted, or C<git checkout If you want to cancel one or several commits, you can use C<git reset>. -=head1 BISECTING +=head1 Bisecting C<git> provides a built-in way to determine, with a binary search in the history, which commit should be blamed for introducing a given bug. @@ -723,14 +727,14 @@ the "first commit where the bug is solved". C<git help bisect> has much more information on how you can tweak your binary searches. -=head1 SUBMITTING A PATCH VIA GITHUB +=head1 Submitting a patch via GitHub GitHub is a website that makes it easy to fork and publish projects with Git. First you should set up a GitHub account and log in. Perl's git repository is mirrored on GitHub at this page: - http://github.com/github/perl/tree/blead + http://github.com/mirrors/perl/tree/blead Visit the page and click the "fork" button. This clones the Perl git repository for you and provides you with "Your Clone URL" from which @@ -749,42 +753,42 @@ The same patch as above, using github might look like this: % git push origin orange The orange branch has been pushed to GitHub, so you should now send an -email (see L</SUBMITTING A PATCH>) with a description of your changes +email (see L</Submitting a patch>) with a description of your changes and the following information: http://github.com/USERNAME/perl/tree/orange - [email protected]:USERNAME/perl.git branch orange + git://github.com/USERNAME/perl.git branch orange -=head1 MERGING FROM A BRANCH VIA GITHUB +=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 dandv + % git remote add avar git://github.com/avar/perl.git + % git fetch avar Now you can see the differences between the branch and blead: - % git diff dandv/blead + % git diff avar/orange And you can see the commits: - % git log dandv/blead + % git log avar/orange If you approve of a specific commit, you can cherry pick it: - % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f + % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae Or you could just merge the whole branch if you like it all: - % git merge dandv/blead + % git merge avar/orange And then push back to the repository: % git push -=head1 TOPIC BRANCHES AND REWRITING HISTORY +=head1 Topic branches and rewriting history Individual committers should create topic branches under B<yourname>/B<some_descriptive_name>. Other committers should check @@ -861,9 +865,10 @@ deleted or modified. Think long and hard about whether you want to push a local tag to perl.git before doing so. (Pushing unannotated tags is not allowed.) -=head1 COMMITTING TO MAINTENANCE VERSIONS +=head1 Committing to maintenance versions -Maintenance versions should only be altered to add critical bug fixes. +Maintenance versions should only be altered to add critical bug +fixes, see L<perlpolicy>. To commit to a maintenance version of perl, you need to create a local tracking branch: @@ -879,7 +884,7 @@ using the C<git cherry-pick> command. It is recommended to use the 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 +=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 @@ -893,9 +898,18 @@ C<.git/info/grafts> file: 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 + +=over +=item * -=head1 SEE ALSO +The git documentation, accessible via the C<git help> command + +=item * -The git documentation, accessible via C<git help command>. +L<perlpolicy> - Perl core development policy + +=back +=cut -- Perl5 Master Repository
