diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlgit.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlgit.pod | 260 |
1 files changed, 126 insertions, 134 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlgit.pod b/Master/tlpkg/tlperl/lib/pods/perlgit.pod index eac7bb84b5e..1d2df2ed5e9 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlgit.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlgit.pod @@ -51,7 +51,7 @@ branches in the repository: The branches that begin with "origin" correspond to the "git remote" that you cloned from (which is named "origin"). Each branch on the -remote will be exactly tracked by theses branches. You should NEVER do +remote will be exactly tracked by these branches. You should NEVER do work on these remote tracking branches. You only ever do work in a local branch. Local branches can be configured to automerge (on pull) from a designated remote tracking branch. This is the case with the @@ -258,7 +258,7 @@ Now you should create a patch file for all your local changes: % git format-patch -M origin.. 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch -You should now send an email to to +You should now send an email to L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your changes, and include this patch file as an attachment. In addition to being tracked by RT, mail to perlbug will automatically be forwarded to @@ -385,45 +385,59 @@ If you want to cancel one or several commits, you can use C<git reset>. =head2 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. - -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. You -need an helper script that automates building C<perl> and running the -testcase: - - % cat ~/run - #!/bin/sh - git clean -dxf - - # If you get './makedepend: 1: Syntax error: Unterminated quoted - # string' when bisecting versions of perl older than 5.9.5 this hack - # will work around the bug in makedepend.SH which was fixed in - # version 96a8704c. Make sure to comment out `git checkout makedepend.SH' - # below too. - git show blead:makedepend.SH > makedepend.SH - - # 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 - perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile - # if you just need miniperl, replace test_prep with miniperl - make test_prep - [ -x ./perl ] || exit 125 - ./perl -Ilib ~/testcase.pl - ret=$? - [ $ret -gt 127 ] && ret=127 - # git checkout makedepend.SH - 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 -F<~/testcase.pl>. +C<git> provides a built-in way to determine which commit should be blamed +for introducing a given bug. C<git bisect> performs a binary search of +history to locate the first failing commit. It is fast, powerful and +flexible, but requires some setup and to automate the process an auxiliary +shell script is needed. + +The core provides a wrapper program, F<Porting/bisect.pl>, which attempts to +simplify as much as possible, making bisecting as simple as running a Perl +one-liner. For example, if you want to know when this became an error: + + perl -e 'my $a := 2' + +you simply run this: + + .../Porting/bisect.pl -e 'my $a := 2;' + +Using C<bisect.pl>, with one command (and no other files) it's easy to find +out + +=over 4 + +=item * + +Which commit caused this example code to break? + +=item * + +Which commit caused this example code to start working? + +=item * + +Which commit added the first file to match this regex? + +=item * + +Which commit removed the last file to match this regex? + +=back + +usually without needing to know which versions of perl to use as start and +end revisions, as F<bisect.pl> automatically searches to find the earliest +stable version for which the test case passes. Run +C<Porting/bisect.pl --help> for the full documentation, including how to +set the C<Configure> and build time options. + +If you require more flexibility than F<Porting/bisect.pl> has to offer, you'll +need to run C<git bisect> yourself. It's most useful to use C<git bisect run> +to automate the building and testing of perl revisions. For this you'll need +a shell script for C<git> to call to test a particular revision. An example +script is F<Porting/bisect-example.sh>, which you should copy B<outside> of +the repository, as the bisect process will reset the state to a clean checkout +as it runs. The instructions below assume that you copied it as F<~/run> and +then edited it as appropriate. You first enter in bisect mode with: @@ -466,6 +480,7 @@ 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 Topic branches and rewriting history Individual committers should create topic branches under @@ -543,7 +558,7 @@ 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.) -=head3 Grafts +=head2 Grafts The perl history contains one mistake which was not caught in the conversion: a merge was recorded in the history between blead and @@ -557,83 +572,6 @@ 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. -=head2 Topic branches and rewriting history - -Individual committers should create topic branches under -B<yourname>/B<some_descriptive_name>. Other committers should check -with a topic branch's creator before making any change to it. - -The simplest way to create a remote topic branch that works on all -versions of git is to push the current head as a new branch on the -remote, then check it out locally: - - $ branch="$yourname/$some_descriptive_name" - $ git push origin HEAD:$branch - $ git checkout -b $branch origin/$branch - -Users of git 1.7 or newer can do it in a more obvious manner: - - $ branch="$yourname/$some_descriptive_name" - $ git checkout -b $branch - $ git push origin -u $branch - -If you are not the creator of B<yourname>/B<some_descriptive_name>, you -might sometimes find that the original author has edited the branch's -history. There are lots of good reasons for this. Sometimes, an author -might simply be rebasing the branch onto a newer source point. -Sometimes, an author might have found an error in an early commit which -they wanted to fix before merging the branch to blead. - -Currently the master repository is configured to forbid -non-fast-forward merges. This means that the branches within can not be -rebased and pushed as a single step. - -The only way you will ever be allowed to rebase or modify the history -of a pushed branch is to delete it and push it as a new branch under -the same name. Please think carefully about doing this. It may be -better to sequentially rename your branches so that it is easier for -others working with you to cherry-pick their local changes onto the new -version. (XXX: needs explanation). - -If you want to rebase a personal topic branch, you will have to delete -your existing topic branch and push as a new version of it. You can do -this via the following formula (see the explanation about C<refspec>'s -in the git push documentation for details) after you have rebased your -branch: - - # first rebase - $ git checkout $user/$topic - $ git fetch - $ git rebase origin/blead - - # then "delete-and-push" - $ git push origin :$user/$topic - $ git push origin $user/$topic - -B<NOTE:> it is forbidden at the repository level to delete any of the -"primary" branches. That is any branch matching -C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git -producing an error like this: - - $ git push origin :blead - *** It is forbidden to delete blead/maint branches in this repository - error: hooks/update exited with error code 1 - error: hook declined to update refs/heads/blead - To ssh://perl5.git.perl.org/perl - ! [remote rejected] blead (hook declined) - error: failed to push some refs to 'ssh://perl5.git.perl.org/perl' - -As a matter of policy we do B<not> edit the history of the blead and -maint-* branches. If a typo (or worse) sneaks into a commit to blead or -maint-*, we'll fix it in another commit. The only types of updates -allowed on these branches are "fast-forward's", where all history is -preserved. - -Annotated tags in the canonical perl.git repository will never be -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 WRITE ACCESS TO THE GIT REPOSITORY Once you have write access, you will need to modify the URL for the @@ -667,6 +605,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>. + =head1 Accepting a patch If you have received a patch file generated using the above section, @@ -763,12 +702,79 @@ look in F<t/porting>. =item * If you make any changes that affect miniperl or core routines that have -different code paths for miniperl, be sure to run C<make minitest>. +different code paths for miniperl, be sure to run C<make minitest>. This will catch problems that even the full test suite will not catch because it runs a subset of tests under miniperl rather than perl. =back +=head3 On merging and rebasing + +Simple, one-off commits pushed to the 'blead' branch should be simple +commits that apply cleanly. In other words, you should make sure your +work is committed against the current position of blead, so that you can +push back to the master repository without merging. + +Sometimes, blead will move while you're building or testing your +changes. When this happens, your push will be rejected with a message +like this: + + To ssh://perl5.git.perl.org/perl.git + ! [rejected] blead -> blead (non-fast-forward) + error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git' + To prevent you from losing history, non-fast-forward updates were rejected + Merge the remote changes (e.g. 'git pull') before pushing again. See the + 'Note about fast-forwards' section of 'git push --help' for details. + +When this happens, you can just I<rebase> your work against the new +position of blead, like this (assuming your remote for the master +repository is "p5p"): + + $ git fetch p5p + $ git rebase p5p/blead + +You will see your commits being re-applied, and you will then be able to +push safely. More information about rebasing can be found in the +documentation for the git-rebase(1) command. + +For larger sets of commits that only make sense together, or that would +benefit from a summary of the set's purpose, you should use a merge +commit. You should perform your work on a L<topic branch|/Topic +branches and rewriting history>, which you should regularly rebase +against blead to ensure that your code is not broken by blead moving. +When you have finished your work, please perform a final rebase and +test. Linear history is something that gets lost with every +commit on blead, but a final rebase makes the history linear +again, making it easier for future maintainers to see what has +happened. Rebase as follows (assuming your work was on the +branch C<< committer/somework >>): + + $ git checkout committer/somework + $ git rebase blead + +Then you can merge it into master like this: + + $ git checkout blead + $ git merge --no-ff --no-commit committer/somework + $ git commit -a + +The switches above deserve explanation. C<--no-ff> indicates that even +if all your work can be applied linearly against blead, a merge commit +should still be prepared. This ensures that all your work will be shown +as a side branch, with all its commits merged into the mainstream blead +by the merge commit. + +C<--no-commit> means that the merge commit will be I<prepared> but not +I<committed>. The commit is then actually performed when you run the +next command, which will bring up your editor to describe the commit. +Without C<--no-commit>, the commit would be made with nearly no useful +message, which would greatly diminish the value of the merge commit as a +placeholder for the work's description. + +When describing the merge commit, explain the purpose of the branch, and +keep in mind that this description will probably be used by the +eventual release engineer when reviewing the next perldelta document. + =head2 Committing to maintenance versions Maintenance versions should only be altered to add critical bug fixes, @@ -791,20 +797,6 @@ original commit in the new commit message. Before pushing any change to a maint version, make sure you've satisfied the steps in L</Committing to blead> above. -=head2 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. - =head2 Merging from a branch via GitHub While we don't encourage the submission of patches via GitHub, that |