1=encoding utf8 2 3=for comment 4Consistent formatting of this file is achieved with: 5 perl ./Porting/podtidy pod/perlgit.pod 6 7=head1 NAME 8 9perlgit - Detailed information about git and the Perl repository 10 11=head1 DESCRIPTION 12 13This document provides details on using git to develop Perl. If you are 14just interested in working on a quick patch, see L<perlhack> first. 15This document is intended for people who are regular contributors to 16Perl, including those with write access to the git repository. 17 18=head1 CLONING THE REPOSITORY 19 20All of Perl's source code is kept centrally in a Git repository at 21I<github.com>. 22 23You can make a read-only clone of the repository by running: 24 25 % git clone git://github.com/Perl/perl5.git perl 26 27This uses the git protocol (port 9418). 28 29If you cannot use the git protocol for firewall reasons, you can also 30clone via http: 31 32 % git clone https://github.com/Perl/perl5.git perl 33 34=head1 WORKING WITH THE REPOSITORY 35 36Once you have changed into the repository directory, you can inspect 37it. After a clone the repository will contain a single local branch, 38which will be the current branch as well, as indicated by the asterisk. 39 40 % git branch 41 * blead 42 43Using the -a switch to C<branch> will also show the remote tracking 44branches in the repository: 45 46 % git branch -a 47 * blead 48 origin/HEAD 49 origin/blead 50 ... 51 52The branches that begin with "origin" correspond to the "git remote" 53that you cloned from (which is named "origin"). Each branch on the 54remote will be exactly tracked by these branches. You should NEVER do 55work on these remote tracking branches. You only ever do work in a 56local branch. Local branches can be configured to automerge (on pull) 57from a designated remote tracking branch. This is the case with the 58default branch C<blead> which will be configured to merge from the 59remote tracking branch C<origin/blead>. 60 61You can see recent commits: 62 63 % git log 64 65And pull new changes from the repository, and update your local 66repository (must be clean first) 67 68 % git pull 69 70Assuming we are on the branch C<blead> immediately after a pull, this 71command would be more or less equivalent to: 72 73 % git fetch 74 % git merge origin/blead 75 76In fact if you want to update your local repository without touching 77your working directory you do: 78 79 % git fetch 80 81And if you want to update your remote-tracking branches for all defined 82remotes simultaneously you can do 83 84 % git remote update 85 86Neither of these last two commands will update your working directory, 87however both will update the remote-tracking branches in your 88repository. 89 90To make a local branch of a remote branch: 91 92 % git checkout -b maint-5.10 origin/maint-5.10 93 94To switch back to blead: 95 96 % git checkout blead 97 98=head2 Finding out your status 99 100The most common git command you will use will probably be 101 102 % git status 103 104This command will produce as output a description of the current state 105of the repository, including modified files and unignored untracked 106files, and in addition it will show things like what files have been 107staged for the next commit, and usually some useful information about 108how to change things. For instance the following: 109 110 % git status 111 On branch blead 112 Your branch is ahead of 'origin/blead' by 1 commit. 113 114 Changes to be committed: 115 (use "git reset HEAD <file>..." to unstage) 116 117 modified: pod/perlgit.pod 118 119 Changes not staged for commit: 120 (use "git add <file>..." to update what will be committed) 121 (use "git checkout -- <file>..." to discard changes in working 122 directory) 123 124 modified: pod/perlgit.pod 125 126 Untracked files: 127 (use "git add <file>..." to include in what will be committed) 128 129 deliberate.untracked 130 131This shows that there were changes to this document staged for commit, 132and that there were further changes in the working directory not yet 133staged. It also shows that there was an untracked file in the working 134directory, and as you can see shows how to change all of this. It also 135shows that there is one commit on the working branch C<blead> which has 136not been pushed to the C<origin> remote yet. B<NOTE>: This output 137is also what you see as a template if you do not provide a message to 138C<git commit>. 139 140=head2 Patch workflow 141 142First, please read L<perlhack> for details on hacking the Perl core. 143That document covers many details on how to create a good patch. 144 145If you already have a Perl repository, you should ensure that you're on 146the I<blead> branch, and your repository is up to date: 147 148 % git checkout blead 149 % git pull 150 151It's preferable to patch against the latest blead version, since this 152is where new development occurs for all changes other than critical bug 153fixes. Critical bug fix patches should be made against the relevant 154maint branches, or should be submitted with a note indicating all the 155branches where the fix should be applied. 156 157Now that we have everything up to date, we need to create a temporary 158new branch for these changes and switch into it: 159 160 % git checkout -b orange 161 162which is the short form of 163 164 % git branch orange 165 % git checkout orange 166 167Creating a topic branch makes it easier for the maintainers to rebase 168or merge back into the master blead for a more linear history. If you 169don't work on a topic branch the maintainer has to manually cherry pick 170your changes onto blead before they can be applied. 171 172That'll get you scolded on perl5-porters, so don't do that. Be Awesome. 173 174Then make your changes. For example, if Leon Brocard changes his name 175to Orange Brocard, we should change his name in the AUTHORS file: 176 177 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS 178 179You can see what files are changed: 180 181 % git status 182 On branch orange 183 Changes to be committed: 184 (use "git reset HEAD <file>..." to unstage) 185 186 modified: AUTHORS 187 188And you can see the changes: 189 190 % git diff 191 diff --git a/AUTHORS b/AUTHORS 192 index 293dd70..722c93e 100644 193 --- a/AUTHORS 194 +++ b/AUTHORS 195 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> 196 Laszlo Molnar <laszlo.molnar@eth.ericsson.se> 197 Leif Huhn <leif@hale.dkstat.com> 198 Len Johnson <lenjay@ibm.net> 199 -Leon Brocard <acme@astray.com> 200 +Orange Brocard <acme@astray.com> 201 Les Peters <lpeters@aol.net> 202 Lesley Binks <lesley.binks@gmail.com> 203 Lincoln D. Stein <lstein@cshl.org> 204 205Now commit your change locally: 206 207 % git commit -a -m 'Rename Leon Brocard to Orange Brocard' 208 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard 209 1 files changed, 1 insertions(+), 1 deletions(-) 210 211The C<-a> option is used to include all files that git tracks that you 212have changed. If at this time, you only want to commit some of the 213files you have worked on, you can omit the C<-a> and use the command 214C<S<git add I<FILE ...>>> before doing the commit. C<S<git add 215--interactive>> allows you to even just commit portions of files 216instead of all the changes in them. 217 218The C<-m> option is used to specify the commit message. If you omit it, 219git will open a text editor for you to compose the message 220interactively. This is useful when the changes are more complex than 221the sample given here, and, depending on the editor, to know that the 222first line of the commit message doesn't exceed the 50 character legal 223maximum. See L<perlhack/Commit message> for more information about what 224makes a good commit message. 225 226Once you've finished writing your commit message and exited your 227editor, git will write your change to disk and tell you something like 228this: 229 230 Created commit daf8e63: explain git status and stuff about remotes 231 1 files changed, 83 insertions(+), 3 deletions(-) 232 233If you re-run C<git status>, you should see something like this: 234 235 % git status 236 On branch orange 237 Untracked files: 238 (use "git add <file>..." to include in what will be committed) 239 240 deliberate.untracked 241 242 nothing added to commit but untracked files present (use "git add" to 243 track) 244 245When in doubt, before you do anything else, check your status and read 246it carefully, many questions are answered directly by the git status 247output. 248 249You can examine your last commit with: 250 251 % git show HEAD 252 253and if you are not happy with either the description or the patch 254itself you can fix it up by editing the files once more and then issue: 255 256 % git commit -a --amend 257 258Now, create a fork on GitHub to push your branch to, and add it as a 259remote if you haven't already, as described in the GitHub documentation 260at L<https://help.github.com/en/articles/working-with-forks>: 261 262 % git remote add fork git@github.com:MyUser/perl5.git 263 264And push the branch to your fork: 265 266 % git push -u fork orange 267 268You should now submit a Pull Request (PR) on GitHub from the new branch 269to blead. For more information, see the GitHub documentation at 270L<https://help.github.com/en/articles/creating-a-pull-request-from-a-fork>. 271 272You can also send patch files to 273L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the 274patch is not ready to be applied, but intended for discussion. 275 276To create a patch file for all your local changes: 277 278 % git format-patch -M blead.. 279 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch 280 281Or for a lot of changes, e.g. from a topic branch: 282 283 % git format-patch --stdout -M blead.. > topic-branch-changes.patch 284 285If you want to delete your temporary branch, you may do so with: 286 287 % git checkout blead 288 % git branch -d orange 289 error: The branch 'orange' is not an ancestor of your current HEAD. 290 If you are sure you want to delete it, run 'git branch -D orange'. 291 % git branch -D orange 292 Deleted branch orange. 293 294=head2 A note on derived files 295 296Be aware that many files in the distribution are derivative--avoid 297patching them, because git won't see the changes to them, and the build 298process will overwrite them. Patch the originals instead. Most 299utilities (like perldoc) are in this category, i.e. patch 300F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't 301create patches for files under F<$src_root/ext> from their copies found 302in F<$install_root/lib>. If you are unsure about the proper location of 303a file that may have gotten copied while building the source 304distribution, consult the F<MANIFEST>. 305 306=head2 Cleaning a working directory 307 308The command C<git clean> can with varying arguments be used as a 309replacement for C<make clean>. 310 311To reset your working directory to a pristine condition you can do: 312 313 % git clean -dxf 314 315However, be aware this will delete ALL untracked content. You can use 316 317 % git clean -Xf 318 319to remove all ignored untracked files, such as build and test 320byproduct, but leave any manually created files alone. 321 322If you only want to cancel some uncommitted edits, you can use C<git 323checkout> and give it a list of files to be reverted, or C<git checkout 324-f> to revert them all. 325 326If you want to cancel one or several commits, you can use C<git reset>. 327 328=head2 Bisecting 329 330C<git> provides a built-in way to determine which commit should be blamed 331for introducing a given bug. C<git bisect> performs a binary search of 332history to locate the first failing commit. It is fast, powerful and 333flexible, but requires some setup and to automate the process an auxiliary 334shell script is needed. 335 336The core provides a wrapper program, F<Porting/bisect.pl>, which attempts to 337simplify as much as possible, making bisecting as simple as running a Perl 338one-liner. For example, if you want to know when this became an error: 339 340 perl -e 'my $a := 2' 341 342you simply run this: 343 344 .../Porting/bisect.pl -e 'my $a := 2;' 345 346Using F<Porting/bisect.pl>, with one command (and no other files) it's easy to 347find out 348 349=over 4 350 351=item * 352 353Which commit caused this example code to break? 354 355=item * 356 357Which commit caused this example code to start working? 358 359=item * 360 361Which commit added the first file to match this regex? 362 363=item * 364 365Which commit removed the last file to match this regex? 366 367=back 368 369usually without needing to know which versions of perl to use as start and 370end revisions, as F<Porting/bisect.pl> automatically searches to find the 371earliest stable version for which the test case passes. Run 372C<Porting/bisect.pl --help> for the full documentation, including how to 373set the C<Configure> and build time options. 374 375If you require more flexibility than F<Porting/bisect.pl> has to offer, you'll 376need to run C<git bisect> yourself. It's most useful to use C<git bisect run> 377to automate the building and testing of perl revisions. For this you'll need 378a shell script for C<git> to call to test a particular revision. An example 379script is F<Porting/bisect-example.sh>, which you should copy B<outside> of 380the repository, as the bisect process will reset the state to a clean checkout 381as it runs. The instructions below assume that you copied it as F<~/run> and 382then edited it as appropriate. 383 384You first enter in bisect mode with: 385 386 % git bisect start 387 388For example, if the bug is present on C<HEAD> but wasn't in 5.10.0, 389C<git> will learn about this when you enter: 390 391 % git bisect bad 392 % git bisect good perl-5.10.0 393 Bisecting: 853 revisions left to test after this 394 395This results in checking out the median commit between C<HEAD> and 396C<perl-5.10.0>. You can then run the bisecting process with: 397 398 % git bisect run ~/run 399 400When the first bad commit is isolated, C<git bisect> will tell you so: 401 402 ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit 403 commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 404 Author: Dave Mitchell <davem@fdisolutions.com> 405 Date: Sat Feb 9 14:56:23 2008 +0000 406 407 [perl #49472] Attributes + Unknown Error 408 ... 409 410 bisect run success 411 412You can peek into the bisecting process with C<git bisect log> and 413C<git bisect visualize>. C<git bisect reset> will get you out of bisect 414mode. 415 416Please note that the first C<good> state must be an ancestor of the 417first C<bad> state. If you want to search for the commit that I<solved> 418some bug, you have to negate your test case (i.e. exit with C<1> if OK 419and C<0> if not) and still mark the lower bound as C<good> and the 420upper as C<bad>. The "first bad commit" has then to be understood as 421the "first commit where the bug is solved". 422 423C<git help bisect> has much more information on how you can tweak your 424binary searches. 425 426Following bisection you may wish to configure, build and test perl at 427commits identified by the bisection process. Sometimes, particularly 428with older perls, C<make> may fail during this process. In this case 429you may be able to patch the source code at the older commit point. To 430do so, please follow the suggestions provided in 431L<perlhack/Building perl at older commits>. 432 433=head2 Topic branches and rewriting history 434 435Individual committers should create topic branches under 436B<yourname>/B<some_descriptive_name>: 437 438 % branch="$yourname/$some_descriptive_name" 439 % git checkout -b $branch 440 ... do local edits, commits etc ... 441 % git push origin -u $branch 442 443Should you be stuck with an ancient version of git (prior to 1.7), then 444C<git push> will not have the C<-u> switch, and you have to replace the 445last step with the following sequence: 446 447 % git push origin $branch:refs/heads/$branch 448 % git config branch.$branch.remote origin 449 % git config branch.$branch.merge refs/heads/$branch 450 451If you want to make changes to someone else's topic branch, you should 452check with its creator before making any change to it. 453 454You 455might sometimes find that the original author has edited the branch's 456history. There are lots of good reasons for this. Sometimes, an author 457might simply be rebasing the branch onto a newer source point. 458Sometimes, an author might have found an error in an early commit which 459they wanted to fix before merging the branch to blead. 460 461Currently the master repository is configured to forbid 462non-fast-forward merges. This means that the branches within can not be 463rebased and pushed as a single step. 464 465The only way you will ever be allowed to rebase or modify the history 466of a pushed branch is to delete it and push it as a new branch under 467the same name. Please think carefully about doing this. It may be 468better to sequentially rename your branches so that it is easier for 469others working with you to cherry-pick their local changes onto the new 470version. (XXX: needs explanation). 471 472If you want to rebase a personal topic branch, you will have to delete 473your existing topic branch and push as a new version of it. You can do 474this via the following formula (see the explanation about C<refspec>'s 475in the git push documentation for details) after you have rebased your 476branch: 477 478 # first rebase 479 % git checkout $user/$topic 480 % git fetch 481 % git rebase origin/blead 482 483 # then "delete-and-push" 484 % git push origin :$user/$topic 485 % git push origin $user/$topic 486 487B<NOTE:> it is forbidden at the repository level to delete any of the 488"primary" branches. That is any branch matching 489C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git 490producing an error like this: 491 492 % git push origin :blead 493 *** It is forbidden to delete blead/maint branches in this repository 494 error: hooks/update exited with error code 1 495 error: hook declined to update refs/heads/blead 496 To ssh://perl5.git.perl.org/perl 497 ! [remote rejected] blead (hook declined) 498 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl' 499 500As a matter of policy we do B<not> edit the history of the blead and 501maint-* branches. If a typo (or worse) sneaks into a commit to blead or 502maint-*, we'll fix it in another commit. The only types of updates 503allowed on these branches are "fast-forwards", where all history is 504preserved. 505 506Annotated tags in the canonical perl.git repository will never be 507deleted or modified. Think long and hard about whether you want to push 508a local tag to perl.git before doing so. (Pushing simple tags is 509not allowed.) 510 511=head2 Grafts 512 513The perl history contains one mistake which was not caught in the 514conversion: a merge was recorded in the history between blead and 515maint-5.10 where no merge actually occurred. Due to the nature of git, 516this is now impossible to fix in the public repository. You can remove 517this mis-merge locally by adding the following line to your 518C<.git/info/grafts> file: 519 520 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930 521 522It is particularly important to have this graft line if any bisecting 523is done in the area of the "merge" in question. 524 525=head1 WRITE ACCESS TO THE GIT REPOSITORY 526 527Once you have write access, you will need to modify the URL for the 528origin remote to enable pushing. Edit F<.git/config> with the 529git-config(1) command: 530 531 % git config remote.origin.url git@github.com:Perl/perl5.git 532 533You can also set up your user name and e-mail address. Most people do 534this once globally in their F<~/.gitconfig> by doing something like: 535 536 % git config --global user.name "Ævar Arnfjörð Bjarmason" 537 % git config --global user.email avarab@gmail.com 538 539However, if you'd like to override that just for perl, 540execute something like the following in F<perl>: 541 542 % git config user.email avar@cpan.org 543 544It is also possible to keep C<origin> as a git remote, and add a new 545remote for ssh access: 546 547 % git remote add camel git@github.com:Perl/perl5.git 548 549This allows you to update your local repository by pulling from 550C<origin>, which is faster and doesn't require you to authenticate, and 551to push your changes back with the C<camel> remote: 552 553 % git fetch camel 554 % git push camel 555 556The C<fetch> command just updates the C<camel> refs, as the objects 557themselves should have been fetched when pulling from C<origin>. 558 559=head2 Working with Github pull requests 560 561Pull requests typically originate from outside of the C<Perl/perl.git> 562repository, so if you want to test or work with it locally a vanilla 563C<git fetch> from the C<Perl/perl5.git> repository won't fetch it. 564 565However Github does provide a mechanism to fetch a pull request to a 566local branch. They are available on Github remotes under C<pull/>, so 567you can use C<< git fetch pull/I<PRID>/head:I<localname> >> to make a 568local copy. eg. to fetch pull request 9999 to the local branch 569C<local-branch-name> run: 570 571 git fetch origin pull/9999/head:local-branch-name 572 573and then: 574 575 git checkout local-branch-name 576 577Note: this branch is not rebased on C<blead>, so instead of the 578checkout above, you might want: 579 580 git rebase origin/blead local-branch-name 581 582which rebases C<local-branch-name> on C<blead>, and checks it out. 583 584Alternatively you can configure the remote to fetch all pull requests 585as remote-tracking branches. To do this edit the remote in 586F<.git/config>, for example if your github remote is C<origin> you'd 587have: 588 589 [remote "origin"] 590 url = git@github.com:/Perl/perl5.git 591 fetch = +refs/heads/*:refs/remotes/origin/* 592 593Add a line to map the remote pull request branches to remote-tracking 594branches: 595 596 [remote "origin"] 597 url = git@github.com:/Perl/perl5.git 598 fetch = +refs/heads/*:refs/remotes/origin/* 599 fetch = +refs/pull/*/head:refs/remotes/origin/pull/* 600 601and then do a fetch as normal: 602 603 git fetch origin 604 605This will create a remote-tracking branch for every pull request, including 606closed requests. 607 608To remove those remote-tracking branches, remove the line added above 609and prune: 610 611 git fetch -p origin # or git remote prune origin 612 613=head2 Accepting a patch 614 615If you have received a patch file generated using the above section, 616you should try out the patch. 617 618First we need to create a temporary new branch for these changes and 619switch into it: 620 621 % git checkout -b experimental 622 623Patches that were formatted by C<git format-patch> are applied with 624C<git am>: 625 626 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch 627 Applying Rename Leon Brocard to Orange Brocard 628 629Note that some UNIX mail systems can mess with text attachments containing 630'From '. This will fix them up: 631 632 % perl -pi -e's/^>From /From /' \ 633 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch 634 635If just a raw diff is provided, it is also possible use this two-step 636process: 637 638 % git apply bugfix.diff 639 % git commit -a -m "Some fixing" \ 640 --author="That Guy <that.guy@internets.com>" 641 642Now we can inspect the change: 643 644 % git show HEAD 645 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 646 Author: Leon Brocard <acme@astray.com> 647 Date: Fri Dec 19 17:02:59 2008 +0000 648 649 Rename Leon Brocard to Orange Brocard 650 651 diff --git a/AUTHORS b/AUTHORS 652 index 293dd70..722c93e 100644 653 --- a/AUTHORS 654 +++ b/AUTHORS 655 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> 656 Laszlo Molnar <laszlo.molnar@eth.ericsson.se> 657 Leif Huhn <leif@hale.dkstat.com> 658 Len Johnson <lenjay@ibm.net> 659 -Leon Brocard <acme@astray.com> 660 +Orange Brocard <acme@astray.com> 661 Les Peters <lpeters@aol.net> 662 Lesley Binks <lesley.binks@gmail.com> 663 Lincoln D. Stein <lstein@cshl.org> 664 665If you are a committer to Perl and you think the patch is good, you can 666then merge it into blead then push it out to the main repository: 667 668 % git checkout blead 669 % git merge experimental 670 % git push origin blead 671 672If you want to delete your temporary branch, you may do so with: 673 674 % git checkout blead 675 % git branch -d experimental 676 error: The branch 'experimental' is not an ancestor of your current 677 HEAD. If you are sure you want to delete it, run 'git branch -D 678 experimental'. 679 % git branch -D experimental 680 Deleted branch experimental. 681 682=head2 Committing to blead 683 684The 'blead' branch will become the next production release of Perl. 685 686Before pushing I<any> local change to blead, it's incredibly important 687that you do a few things, lest other committers come after you with 688pitchforks and torches: 689 690=over 691 692=item * 693 694Make sure you have a good commit message. See L<perlhack/Commit 695message> for details. 696 697=item * 698 699Run the test suite. You might not think that one typo fix would break a 700test file. You'd be wrong. Here's an example of where not running the 701suite caused problems. A patch was submitted that added a couple of 702tests to an existing F<.t>. It couldn't possibly affect anything else, so 703no need to test beyond the single affected F<.t>, right? But, the 704submitter's email address had changed since the last of their 705submissions, and this caused other tests to fail. Running the test 706target given in the next item would have caught this problem. 707 708=item * 709 710If you don't run the full test suite, at least C<make test_porting>. 711This will run basic sanity checks. To see which sanity checks, have a 712look in F<t/porting>. 713 714=item * 715 716If you make any changes that affect miniperl or core routines that have 717different code paths for miniperl, be sure to run C<make minitest>. 718This will catch problems that even the full test suite will not catch 719because it runs a subset of tests under miniperl rather than perl. 720 721=back 722 723=head2 On merging and rebasing 724 725Simple, one-off commits pushed to the 'blead' branch should be simple 726commits that apply cleanly. In other words, you should make sure your 727work is committed against the current position of blead, so that you can 728push back to the master repository without merging. 729 730Sometimes, blead will move while you're building or testing your 731changes. When this happens, your push will be rejected with a message 732like this: 733 734 To ssh://perl5.git.perl.org/perl.git 735 ! [rejected] blead -> blead (non-fast-forward) 736 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git' 737 To prevent you from losing history, non-fast-forward updates were 738 rejected Merge the remote changes (e.g. 'git pull') before pushing 739 again. See the 'Note about fast-forwards' section of 'git push --help' 740 for details. 741 742When this happens, you can just I<rebase> your work against the new 743position of blead, like this (assuming your remote for the master 744repository is "p5p"): 745 746 % git fetch p5p 747 % git rebase p5p/blead 748 749You will see your commits being re-applied, and you will then be able to 750push safely. More information about rebasing can be found in the 751documentation for the git-rebase(1) command. 752 753For larger sets of commits that only make sense together, or that would 754benefit from a summary of the set's purpose, you should use a merge 755commit. You should perform your work on a L<topic branch|/Topic 756branches and rewriting history>, which you should regularly rebase 757against blead to ensure that your code is not broken by blead moving. 758When you have finished your work, please perform a final rebase and 759test. Linear history is something that gets lost with every 760commit on blead, but a final rebase makes the history linear 761again, making it easier for future maintainers to see what has 762happened. Rebase as follows (assuming your work was on the 763branch C<< committer/somework >>): 764 765 % git checkout committer/somework 766 % git rebase blead 767 768Then you can merge it into master like this: 769 770 % git checkout blead 771 % git merge --no-ff --no-commit committer/somework 772 % git commit -a 773 774The switches above deserve explanation. C<--no-ff> indicates that even 775if all your work can be applied linearly against blead, a merge commit 776should still be prepared. This ensures that all your work will be shown 777as a side branch, with all its commits merged into the mainstream blead 778by the merge commit. 779 780C<--no-commit> means that the merge commit will be I<prepared> but not 781I<committed>. The commit is then actually performed when you run the 782next command, which will bring up your editor to describe the commit. 783Without C<--no-commit>, the commit would be made with nearly no useful 784message, which would greatly diminish the value of the merge commit as a 785placeholder for the work's description. 786 787When describing the merge commit, explain the purpose of the branch, and 788keep in mind that this description will probably be used by the 789eventual release engineer when reviewing the next perldelta document. 790 791=head2 Committing to maintenance versions 792 793Maintenance versions should only be altered to add critical bug fixes, 794see L<perlpolicy>. 795 796To commit to a maintenance version of perl, you need to create a local 797tracking branch: 798 799 % git checkout --track -b maint-5.005 origin/maint-5.005 800 801This creates a local branch named C<maint-5.005>, which tracks the 802remote branch C<origin/maint-5.005>. Then you can pull, commit, merge 803and push as before. 804 805You can also cherry-pick commits from blead and another branch, by 806using the C<git cherry-pick> command. It is recommended to use the 807B<-x> option to C<git cherry-pick> in order to record the SHA1 of the 808original commit in the new commit message. 809 810Before pushing any change to a maint version, make sure you've 811satisfied the steps in L</Committing to blead> above. 812 813=head2 Using a smoke-me branch to test changes 814 815Sometimes a change affects code paths which you cannot test on the OSes 816which are directly available to you and it would be wise to have users 817on other OSes test the change before you commit it to blead. 818 819Fortunately, there is a way to get your change smoke-tested on various 820OSes: push it to a "smoke-me" branch and wait for certain automated 821smoke-testers to report the results from their OSes. 822A "smoke-me" branch is identified by the branch name: specifically, as 823seen on github.com it must be a local branch whose first name 824component is precisely C<smoke-me>. 825 826The procedure for doing this is roughly as follows (using the example of 827tonyc's smoke-me branch called win32stat): 828 829First, make a local branch and switch to it: 830 831 % git checkout -b win32stat 832 833Make some changes, build perl and test your changes, then commit them to 834your local branch. Then push your local branch to a remote smoke-me 835branch: 836 837 % git push origin win32stat:smoke-me/tonyc/win32stat 838 839Now you can switch back to blead locally: 840 841 % git checkout blead 842 843and continue working on other things while you wait a day or two, 844keeping an eye on the results reported for your smoke-me branch at 845L<http://perl.develop-help.com/?b=smoke-me/tonyc/win32state>. 846 847If all is well then update your blead branch: 848 849 % git pull 850 851then checkout your smoke-me branch once more and rebase it on blead: 852 853 % git rebase blead win32stat 854 855Now switch back to blead and merge your smoke-me branch into it: 856 857 % git checkout blead 858 % git merge win32stat 859 860As described earlier, if there are many changes on your smoke-me branch 861then you should prepare a merge commit in which to give an overview of 862those changes by using the following command instead of the last 863command above: 864 865 % git merge win32stat --no-ff --no-commit 866 867You should now build perl and test your (merged) changes one last time 868(ideally run the whole test suite, but failing that at least run the 869F<t/porting/*.t> tests) before pushing your changes as usual: 870 871 % git push origin blead 872 873Finally, you should then delete the remote smoke-me branch: 874 875 % git push origin :smoke-me/tonyc/win32stat 876 877(which is likely to produce a warning like this, which can be ignored: 878 879 remote: fatal: ambiguous argument 880 'refs/heads/smoke-me/tonyc/win32stat': 881 unknown revision or path not in the working tree. 882 remote: Use '--' to separate paths from revisions 883 884) and then delete your local branch: 885 886 % git branch -d win32stat 887