release_managers_guide.pod revision 1.1
1=head1 NAME 2 3release_managers_guide - Releasing a new version of perl 5.x 4 5As of August 2009, this file is mostly complete, although it is missing 6some detail on doing a major release (e.g. 5.10.0 -> 5.12.0). Note that 7things change at each release, so there may be new things not covered 8here, or tools may need updating. 9 10=head1 SYNOPSIS 11 12This document describes the series of tasks required - some automatic, some 13manual - to produce a perl release of some description, be that a snaphot, 14release candidate, or final, numbered release of maint or blead. 15 16The release process has traditionally been executed by the current 17pumpking. 18 19This document both helps as a check-list for the release engineer 20and is a base for ideas on how the various tasks could be automated 21or distributed. 22 23The outline of a typical release cycle is as follows: 24 25 (5.10.1 is released, and post-release actions have been done) 26 27 ...time passes... 28 29 an occasional snapshot is released, that still identifies itself as 30 5.10.1 31 32 ...time passes... 33 34 a few weeks before the release, a number of steps are performed, 35 including bumping the version to 5.10.2 36 37 ...a few weeks passes... 38 39 perl-5.10.2-RC1 is released 40 41 perl-5.10.2 is released 42 43 post-release actions are performed, including creating new 44 perl5103delta.pod 45 46 ... the cycle continues ... 47 48=head1 DETAILS 49 50Some of the tasks described below apply to all four types of 51release of Perl. (snapshot, RC, final release of maint, final 52release of blead). Some of these tasks apply only to a subset 53of these release types. If a step does not apply to a given 54type of release, you will see a notation to that effect at 55the beginning of the step. 56 57=head2 Release types 58 59=over 4 60 61=item Snapshot 62 63A snapshot is intended to encourage in-depth testing from time-to-time, 64for example after a key point in the stabilisation of a branch. It 65requires fewer steps than a full release, and the version number of perl in 66the tarball will usually be the same as that of the previous release. 67 68=item Release Candidate (RC) 69 70A release candidate is an attempt to produce a tarball that is a close as 71possible to the final release. Indeed, unless critical faults are found 72during the RC testing, the final release will be identical to the RC 73barring a few minor fixups (updating the release date in F<perlhist.pod>, 74removing the RC status from F<patchlevel.h>, etc). If faults are found, 75then the fixes should be put into a new release candidate, never directly 76into a final release. 77 78=item Stable/Maint release 79 80At this point you should have a working release candidate with few or no 81changes since. 82 83It's essentially the same procedure as for making a release candidate, but 84with a whole bunch of extra post-release steps. 85 86=item Blead release 87 88It's essentially the same procedure as for making a release candidate, but 89with a whole bunch of extra post-release steps. 90 91=back 92 93=head2 Prerequisites 94 95Before you can make an official release of perl, there are a few 96hoops you need to jump through: 97 98=over 4 99 100=item PAUSE account 101 102I<SKIP this step for SNAPSHOT> 103 104Make sure you have a PAUSE account suitable for uploading a perl release. 105If you don't have a PAUSE account, then request one: 106 107 https://pause.perl.org/pause/query?ACTION=request_id 108 109Check that your account is allowed to upload perl distros: goto 110https://pause.perl.org/, login, then select 'upload file to CPAN'; there 111should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas 112K��nig to add your ID to the list of people allowed to upload something 113called perl. You can find Andreas' email address at: 114 115 https://pause.perl.org/pause/query?ACTION=pause_04imprint 116 117=item CPAN mirror 118 119Some release engineering steps require a full mirror of the CPAN. 120Work to fall back to using a remote mirror via HTTP is incomplete 121but ongoing. (No, a minicpan mirror is not sufficient) 122 123=item git checkout and commit bit 124 125You will need a working C<git> installation, checkout of the perl 126git repository and perl commit bit. For information about working 127with perl and git, see F<pod/perlrepository.pod>. 128 129If you are not yet a perl committer, you won't be able to make a 130release. Have a chat with whichever evil perl porter tried to talk 131you into the idea in the first place to figure out the best way to 132resolve the issue. 133 134 135=item Quotation for release announcement epigraph 136 137I<SKIP this step for SNAPSHOT and RC> 138 139For a numbered blead or maint release of perl, you will need a quotation 140to use as an epigraph to your release announcement. (There's no harm 141in having one for a snapshot, but it's not required). 142 143 144=back 145 146 147=head2 Building a release - advance actions 148 149The work of building a release candidate for a numbered release of 150perl generally starts several weeks before the first release candidate. 151Some of the following steps should be done regularly, but all I<must> be 152done in the run up to a release. 153 154=over 4 155 156=item * 157 158I<You MAY SKIP this step for SNAPSHOT> 159 160Ensure that dual-life CPAN modules are synchronised with CPAN. Basically, 161run the following: 162 163 $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs 164 165to see any inconsistencies between the core and CPAN versions of distros, 166then fix the core, or cajole CPAN authors as appropriate. See also the 167C<-d> and C<-v> options for more detail. You'll probably want to use the 168C<-c cachedir> option to avoid repeated CPAN downloads. 169 170To see which core distro versions differ from the current CPAN versions: 171 172 $ ./perl -Ilib Porting/core-cpan-diff -x -a 173 174If you are making a maint release, run C<core-cpan-diff> on both blead and 175maint, then diff the two outputs. Compare this with what you expect, and if 176necessary, fix things up. For example, you might think that both blead 177and maint are synchronised with a particular CPAN module, but one might 178have some extra changes. 179 180=item * 181 182I<You MAY SKIP this step for SNAPSHOT> 183 184Ensure dual-life CPAN modules are stable, which comes down to: 185 186 for each module that fails its regression tests on $current 187 did it fail identically on $previous? 188 if yes, "SEP" (Somebody Else's Problem) 189 else work out why it failed (a bisect is useful for this) 190 191 attempt to group failure causes 192 193 for each failure cause 194 is that a regression? 195 if yes, figure out how to fix it 196 (more code? revert the code that broke it) 197 else 198 (presumably) it's relying on something un-or-under-documented 199 should the existing behaviour stay? 200 yes - goto "regression" 201 no - note it in perldelta as a significant bugfix 202 (also, try to inform the module's author) 203 204=item * 205 206I<You MAY SKIP this step for SNAPSHOT> 207 208Similarly, monitor the smoking of core tests, and try to fix. 209 210=item * 211 212I<You MAY SKIP this step for SNAPSHOT> 213 214Similarly, monitor the smoking of perl for compiler warnings, and try to 215fix. 216 217=item * 218 219I<You MAY SKIP this step for SNAPSHOT> 220 221Run F<Porting/cmpVERSION.pl> to compare the current source tree with the 222previous version to check for for modules that have identical version 223numbers but different contents, e.g.: 224 225 $ cd ~/some-perl-root 226 $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 . 227 228then bump the version numbers of any non-dual-life modules that have 229changed since the previous release, but which still have the old version 230number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x), 231then compare against both. 232 233Note that some of the files listed may be generated (e.g. copied from ext/ 234to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm); 235make sure you edit the correct file! 236 237Once all version numbers have been bumped, re-run the checks. 238 239Then run again without the -x option, to check that dual-life modules are 240also sensible. 241 242=item * 243 244I<You MAY SKIP this step for SNAPSHOT> 245 246Get perldelta in a mostly finished state. 247 248Peruse F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that 249every section it lists is, if necessary, populated and complete. Copy 250edit the whole document. 251 252=item * 253 254I<You MUST SKIP this step for SNAPSHOT> 255 256A week or two before the first release candidate, bump the perl version 257number (e.g. from 5.10.0 to 5.10.1), to allow sufficient time for testing 258and smoking with the target version built into the perl executable. For 259subsequent release candidates and the final release, it it not necessary 260to bump the version further. 261 262There is a tool to semi-automate this process. It works in two stages. 263First, it generates a list of suggested changes, which you review and 264edit; then you feed this list back and it applies the edits. So, first 265scan the source directory looking for likely candidates. The command line 266arguments are the old and new version numbers, and -s means scan: 267 268 $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan 269 270This produces a file containing a list of suggested edits, e.g.: 271 272 NetWare/Makefile 273 274 89: -MODULE_DESC = "Perl 5.10.0 for NetWare" 275 +MODULE_DESC = "Perl 5.10.1 for NetWare" 276 277i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown. 278Review the file carefully, and delete any -/+ line pairs that you don't 279want changing. You can also edit just the C<+> line to change the 280suggested replacement text. Remember that this tool is largely just 281grepping for '5.10.0' or whatever, so it will generate false positives. Be 282careful not change text like "this was fixed in 5.10.0"! Then run: 283 284 $ Porting/bump-perl-version -u < /tmp/scan 285 286which will update all the files shown; then commit the changes. 287 288Be particularly careful with F<INSTALL>, which contains a mixture of 289C<5.10.0>-type strings, some of which need bumping on every release, and 290some of which need to be left unchanged. Also note that this tool 291currently only detects a single substitution per line: so in particular, 292this line in README.vms needs special handling: 293 294 rename perl-5^.10^.1.dir perl-5_10_1.dir 295 296 297=item * 298 299I<You MUST SKIP this step for SNAPSHOT> 300 301Review and update INSTALL to account for the change in version number; 302in particular, the "Coexistence with earlier versions of perl 5" section. 303 304=item * 305 306I<You MUST SKIP this step for SNAPSHOT> 307 308Update the F<Changes> file to contain the git log command which would show 309all the changes in this release. You will need assume the existence of a 310not-yet created tag for the forthcoming release; e.g. 311 312 git log ... perl-5.10.0..perl5.12.0 313 314Due to warts in the perforce-to-git migration, some branches require extra 315exclusions to avoid other branches being pulled in. Make sure you have the 316correct incantation: replace the not-yet-created tag with C<HEAD> and see 317if C<git log> produces roughly the right number of commits across roughly the 318right time period (you may find C<git log --pretty=oneline | wc> useful). 319 320=item * 321 322Check some more build configurations. The check that setuid builds and 323installs is for < 5.11.0 only. 324 325 $ sh Configure -Dprefix=/tmp/perl-5.x.y -Uinstallusrbinperl \ 326 -Duseshrplib -Dd_dosuid 327 $ make 328 $ LD_LIBRARY_PATH=`pwd` make test # or similar for useshrplib 329 330 $ make suidperl 331 $ su -c 'make install' 332 $ ls -l .../bin/sperl 333 -rws--x--x 1 root root 69974 2009-08-22 21:55 .../bin/sperl 334 335(Then delete the installation directory.) 336 337XXX think of other configurations that need testing. 338 339=item * 340 341I<You MAY SKIP this step for SNAPSHOT> 342 343Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if 344necessary, update the script to include new alias mappings for porters 345already in F<AUTHORS> 346 347 $ git log | perl Porting/checkAUTHORS.pl --acknowledged AUTHORS - 348 349=back 350 351=head2 Building a release - on the day 352 353This section describes the actions required to make a release (or snapshot 354etc) that are performed on the actual day. 355 356=over 4 357 358=item * 359 360Review all the items in the previous section, 361L<"Building a release - advance actions"> to ensure they are all done and 362up-to-date. 363 364=item * 365 366I<You MAY SKIP this step for SNAPSHOT> 367 368Re-read the perldelta to try to find any embarrassing typos and thinkos; 369remove any C<TODO> or C<XXX> flags; update the "Known Problems" section 370with any serious issues for which fixes are not going to happen now; and 371run through pod and spell checkers, e.g. 372 373 $ podchecker -warnings -warnings pod/perl5101delta.pod 374 $ spell pod/perl5101delta.pod 375 376Also, you may want to generate and view an HTML version of it to check 377formatting, e.g. 378 379 $ perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html 380 381=item * 382 383Make sure you have a gitwise-clean perl directory (no modified files, 384unpushed commits etc): 385 386 $ git status 387 388=item * 389 390If not already built, Configure and build perl so that you have a Makefile 391and porting tools: 392 393 $ ./Configure -Dusedevel -des && make 394 395=item * 396 397Check that files managed by F<regen.pl> and friends are up to date. From 398within your working directory: 399 400 $ git status 401 $ make regen 402 $ make regen_perly 403 $ git status 404 405If any of the files managed by F<regen.pl> have changed, then you should 406re-make perl to check that it's okay, then commit the updated versions: 407 408 $ git commit -a -m 'make regn; make regn_perly' 409 410=item * 411 412Rebuild META.yml: 413 414 $ rm META.yml 415 $ make META.yml 416 $ git diff 417 418XXX it would be nice to make Porting/makemeta use regen_lib.pl 419to get the same 'update the file if its changed' functionality 420we get with 'make regen' etc. 421 422Commit META.yml if it has changed: 423 424 $ git commit -m 'Update META.yml' META.yml 425 426=item * 427 428I<You MUST SKIP this step for SNAPSHOT> 429 430Update C<Module::Corelist> with module version data for the new release. 431 432Note that if this is a maint release, you should run the following actions 433from the maint directory, but commit the C<Corelist.pm> changes in 434I<blead> and subsequently cherry-pick it. 435 436F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived 437modules on CPAN. It can use a full, local CPAN mirror or fall back 438to C<wget> or C<curl> to fetch only package metadata remotely. 439 440(If you'd prefer to have a full CPAN mirror, see 441http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN) 442 443Then change to your perl checkout, and if necessary, 444 445 $ make perl 446 447If this not the first update for this version, first edit 448F<lib/Module/CoreList.pm>to delete the existing entries for this version 449from the C<%released> and C<%version> hashes: they will have a key like 450C<5.010001> for 5.10.1. 451 452XXX the edit-in-place functionality of Porting/corelist.pl should 453be fixed to handle this automatically. 454 455Then, If you have a local CPAN mirror, run: 456 457 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror 458 459Otherwise, run: 460 461 $ ./perl -Ilib Porting/corelist.pl cpan 462 463This will chug for a while, possibly reporting various warnings about 464badly-indexed CPABN modules unreltaed to the modules actually in core. 465Assuming all goes well, it will update F<lib/Module/CoreList.pm>. 466 467Check that file over carefully: 468 469 $ git diff lib/Module/CoreList.pm 470 471If necessary, bump C<$VERSION> (there's no need to do this for 472every RC; in RC1, bump the version to a new clean number that will 473appear in the final release, and leave as-is for the later RCs and final). 474 475Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >> 476entry, as that is likely to reflect the previous version number. 477 478In addition, if this is a final release (rather than a release candidate): 479 480=over 4 481 482=item * 483 484Update this version's entry in the C<%released> hash with today's date. 485 486=item * 487 488Make sure that the script has correctly updated the C<CAVEATS> section 489 490=back 491 492Finally, commit the new version of Module::CoreList: 493(unless this is for maint; in which case commit it blead first, then 494cherry-pick it back). 495 496 $ git commit -m 'Update Module::CoreList for 5.x.y' lib/Module/CoreList.pm 497 498=item * 499 500Check that the manifest is sorted and correct: 501 502 $ make manisort 503 $ make distclean 504 $ perl Porting/manicheck 505 $ git status 506 507Commit MANIFEST if it has changed: 508 509 $ git commit -m 'Update MANIFEST' MANIFEST 510 511=item * 512 513I<You MUST SKIP this step for SNAPSHOT> 514 515Add an entry to F<pod/perlhist.pod> with the current date, e.g.: 516 517 David 5.10.1-RC1 2009-Aug-06 518 519Make sure that the correct pumpking is listed in the left-hand column, and 520if this is the first release under the stewardship of a new pumpking, make 521sure that his or her name is listed in the section entitled 522C<THE KEEPERS OF THE PUMPKIN>. 523 524Be sure to commit your changes: 525 526 $ git commit -m 'add new release to perlhist' pod/perlhist.pod 527 528=item * 529 530I<You MUST SKIP this step for SNAPSHOT> 531 532Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is 533a final release, remove it. For example: 534 535 static const char * const local_patches[] = { 536 NULL 537 + ,"RC1" 538 PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ 539 540Be sure to commit your change: 541 542 $ git commit -m 'bump version to RCnnn' patchlevel.h 543 544=item * 545 546Build perl, then make sure it passes its own test suite, and installs: 547 548 $ git clean -xdf 549 $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest 550 551 # or if it's an odd-numbered version: 552 $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest 553 554 $ make test install 555 556=item * 557 558Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and 559C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected, 560especially as regards version numbers, patch and/or RC levels, and @INC 561paths. Note that as they have been been built from a git working 562directory, they will still identify themselves using git tags and 563commits. 564 565Then delete the temporary installation. 566 567=item * 568 569If this is maint release, make sure F<Porting/mergelog> is saved and 570committed. 571 572=item * 573 574Push all your recent commits: 575 576 $ git push origin .... 577 578 579=item * 580 581Create a tarball. Use the C<-s> option to specify a suitable suffix for 582the tarball and directory name: 583 584 $ cd root/of/perl/tree 585 $ make distclean 586 $ git clean -xdf # make sure perl and git agree on files 587 588 $ perl Porting/makerel -b -s `git describe` # for a snapshot 589 $ perl Porting/makerel -b -s RC1 # for a release candidate 590 $ perl Porting/makerel -b # for a final release 591 592This creates the directory F<../perl-x.y.z-RC1> or similar, copies all 593the MANIFEST files into it, sets the correct permissions on them, 594adds DOS line endings to some, then tars it up as 595F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file. 596 597XXX if we go for extra tags and branches stuff, then add the extra details 598here 599 600=item * 601 602Clean up the temporary directory, e.g. 603 604 $ rm -rf ../perl-x.y.z-RC1 605 606=item * 607 608Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you 609have access to. 610 611=item * 612 613Download the tarball to some other machine. For a release candidate, 614you really want to test your tarball on two or more different platforms 615and architectures. The #p5p IRC channel on irc.perl.org is a good place 616to find willing victims. 617 618=item * 619 620Check that basic configuration and tests work on each test machine: 621 622 $ ./Configure -des && make all test 623 624=item * 625 626Check that the test harness and install work on each test machine: 627 628 $ make distclean 629 $ ./Configure -des -Dprefix=/install/path && make all test_harness install 630 $ cd /install/path 631 632=item * 633 634Check that the output of C<perl -v> and C<perl -V> are as expected, 635especially as regards version numbers, patch and/or RC levels, and @INC 636paths. 637 638Note that the results may be different without a F<.git/> directory, 639which is why you should test from the tarball. 640 641=item * 642 643Run the Installation Verification Procedure utility: 644 645 $ bin/perlivp 646 ... 647 All tests successful. 648 $ 649 650=item * 651 652Compare the pathnames of all installed files with those of the previous 653release (i.e. against the last installed tarball on this branch which you 654have previously verified using this same procedure). In particular, look 655for files in the wrong place, or files no longer included which should be. 656For example, suppose the about-to-be-released version is 5.10.1 and the 657previous is 5.10.0: 658 659 cd installdir-5.10.0/ 660 find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1 661 cd installdir-5.10.1/ 662 find . -type f | sort > /tmp/f2 663 diff -u /tmp/f[12] 664 665=item * 666 667Bootstrap the CPAN client on the clean install: 668 669 $ ./bin/perl -MCPAN -e'shell' 670 671=item * 672 673Try installing a popular CPAN module that's reasonably complex and that 674has dependencies; for example: 675 676 CPAN> install Inline 677 CPAN> quit 678 679Check that your perl can run this: 680 681 $ ./bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f' 682 42 683 $ 684 685=item * 686 687Bootstrap the CPANPLUS client on the clean install: 688 689 $ ./bin/cpanp 690 691=item * 692 693Install an XS module, for example: 694 695 CPAN Terminal> i DBI 696 CPAN Terminal> quit 697 $ bin/perl -MDBI -e 1 698 699 700=item * 701 702I<You MAY SKIP this step for SNAPSHOT> 703 704Check that the C<perlbug> utility works. Try the following: 705 706 $ bin/perlbug 707 ... 708 Subject: test bug report 709 Local perl administrator [yourself]: 710 Editor [vi]: 711 Module: 712 Category [core]: 713 Severity [low]: 714 (edit report) 715 Action (Send/Display/Edit/Subject/Save to File): f 716 Name of file to save message in [perlbug.rep]: 717 Action (Send/Display/Edit/Subject/Save to File): q 718 719and carefully examine the output (in F<perlbug.rep]>), especially 720the "Locally applied patches" section. If everything appears okay, then 721try it again, this time actually submitting the bug report. Check that it 722shows up, then remember to close it! 723 724=item * 725 726I<You MAY SKIP this step for SNAPSHOT> 727 728Wait for the smoke tests to catch up with the commit which this release is 729based on (or at least the last commit of any consequence). 730 731Then check that the smoke tests pass (particularly on Win32). If not, go 732back and fix things. 733 734 735=item * 736 737I<You MUST SKIP this step for SNAPSHOT> 738 739Once smoking is okay, upload it to PAUSE. This is the point of no return. 740If anything goes wrong after this point, you will need to re-prepare 741a new release with a new minor version or RC number. 742 743 https://pause.perl.org/ 744 745(Login, then select 'Upload a file to CPAN') 746 747Upload both the .gz and .bz2 versions of the tarball. 748 749=item * 750 751I<You MUST SKIP this step for SNAPSHOT> 752 753Create a tag for the exact git revision you built the release from. 754C<commit> below is the commit corresponding to the tarball. It can be 755omitted if there have been no further commits since the tarball was 756created. 757 758 $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' <commit> 759 $ git push origin tag perl-5.10.1-RC1 760 761=item * 762 763I<You MUST SKIP this step for SNAPSHOT> 764 765Disarm the F<patchlevel.h> change; for example, 766 767 static const char * const local_patches[] = { 768 NULL 769 - ,"RC1" 770 PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ 771 772Be sure to commit your change: 773 774 $ git commit -m 'disarm RCnnn bump' patchlevel.h 775 $ git push origin .... 776 777 778=item * 779 780Mail p5p to announce your new release, with a quote you prepared earlier. 781 782=item * 783 784I<You MAY SKIP this step for SNAPSHOT> 785 786Wait 24 hours or so, then post the announcement to use.perl.org. 787(if you don't have access rights to post news, ask someone like Rafael to 788do it for you.) 789 790=item * 791 792I<You MUST SKIP this step for SNAPSHOT> 793 794Ask Jarkko to add the tarball to http://www.cpan.org/src/ 795 796=item * 797 798I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> 799 800Ask Jarkko to update the descriptions of which tarballs are current in 801http://www.cpan.org/src/README.html, and Rafael to update 802http://dev.perl.org/perl5/ 803 804=item * 805 806I<You MUST SKIP this step for SNAPSHOT, RC> 807 808Create a new empty perlNNNdelta.pod file for the current release + 1; 809see F<Porting/how_to_write_a_perldelta.pod>. 810[ XXX Perhaps we should have an empty template file we can copy in. ] 811 812In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous 813entry as 'D', 814 815Change perlNNNdelta references to the new version in these files 816 817 INSTALL 818 win32/Makefile.mk 819 win32/Makefile 820 Makefile.SH 821 README 822 823Also, edit the previous delta file to change the C<NAME> from C<perldelta> 824to C<perlNNNdelta>. 825 826These two lists of files probably aren't exhaustive; do a recursive grep 827on the previous filename to look for suitable candidates. 828 829(see 16410843ea for an example). 830 831=item * 832 833Run C<perl pod/buildtoc --build-all> to update the following files: 834 835 MANIFEST 836 pod/perl.pod 837 win32/pod.mak 838 vms/descrip_mms.template 839 840If you modified perldelta.pod, (F<vms/descrip_mms.template> will 841needs a manual edit to bump the C<perldelta.pod> entry - it would 842be good for someone to figure out the fix.) 843 844=item * 845 846I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> 847 848If this was a maint release, then edit F<Porting/mergelog> to change 849all the C<d> (deferred) flags to C<.> (needs review). 850 851=item * 852 853I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> 854 855If this was a major release (5.x.0), then create a new maint branch 856based on the commit tagged as the current release and bump the version 857in the blead branch in git, e.g. 5.12.0 to 5.13.0. 858 859[ XXX probably lots more stuff to do, including perldelta, 860C<lib/feature.pm> ] 861 862XXX need a git recipe 863 864=item * 865 866I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> 867 868Copy the perlNNNdelta.pod for this release into the other branches, and 869remember to update these files on those branches too: 870 871 MANIFEST 872 pod.lst 873 pod/perl.pod 874 vms/descrip_mms.template 875 win32/pod.mak 876 877(see fc5be80860 for an example). 878 879=item * 880 881I<You MUST SKIP this step for SNAPSHOT> 882 883Make sure any recent F<pod/perlhist.pod> entries are copied to 884F<perlhist.pod> on other branches; typically the RC* and final entries, 885e.g. 886 887 5.8.9-RC1 2008-Nov-10 888 5.8.9-RC2 2008-Dec-06 889 5.8.9 2008-Dec-14 890 891=item * 892 893I<You MUST SKIP this step for SNAPSHOT, RC> 894 895Remind the current maintainer of C<Module::CoreList> to push a new release 896to CPAN. 897 898=item * 899 900I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some much-needed 901rest and relaxation>. 902 903Thanks for releasing perl! 904 905=back 906 907=head1 SOURCE 908 909Based on 910http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html, 911plus a whole bunch of other sources, including private correspondence. 912 913=cut 914 915