1=encoding utf8 2 3=head1 NAME 4 5release_managers_guide - Releasing a new version of perl 5.x 6 7Note that things change at each release, so there may be new things not 8covered here, or tools may need updating. 9 10=head1 MAKING A CHECKLIST 11 12If you are preparing to do a release, you can run the 13F<Porting/make-rmg-checklist> script to generate a new version of this 14document that starts with a checklist for your release. 15 16This script is run as: 17 18 perl Porting/make-rmg-checklist \ 19 --version [5.x.y-RC#] > /tmp/rmg.pod 20 21You can also pass the C<--html> flag to generate an HTML document instead of 22POD. 23 24 perl Porting/make-rmg-checklist --html \ 25 --version [5.x.y-RC#] > /tmp/rmg.html 26 27=head1 SYNOPSIS 28 29This document describes the series of tasks required - some automatic, some 30manual - to produce a perl release of some description, be that a release 31candidate, or final, numbered release of maint or blead. 32 33New releases of perl are made each month on the 20th by a release engineer 34appointed by the Steering Council. The release engineer roster and schedule 35can be found in Porting/release_schedule.pod. 36 37This document both helps as a check-list for the release engineer 38and is a base for ideas on how the various tasks could be automated 39or distributed. 40 41The checklist of a typical release cycle is as follows: 42 43 (5.10.1 is released, and post-release actions have been done) 44 45 ...time passes... 46 47 a few weeks before the release, a number of steps are performed, 48 including bumping the version to 5.10.2 49 50 ...a few weeks pass... 51 52 perl-5.10.2-RC1 is released 53 54 perl-5.10.2 is released 55 56 post-release actions are performed, including creating new 57 perldelta.pod 58 59 ... the cycle continues ... 60 61=head1 DETAILS 62 63Some of the tasks described below apply to all four types of 64release of Perl. (blead, RC, final release of maint, final 65release of blead). Some of these tasks apply only to a subset 66of these release types. If a step does not apply to a given 67type of release, you will see a notation to that effect at 68the beginning of the step. 69 70=head2 Release types 71 72=over 4 73 74=item Release Candidate (RC) 75 76A release candidate is an attempt to produce a tarball that is a close as 77possible to the final release. Indeed, unless critical faults are found 78during the RC testing, the final release will be identical to the RC 79barring a few minor fixups (updating the release date in F<perlhist.pod>, 80removing the RC status from F<patchlevel.h>, etc). If faults are found, 81then the fixes should be put into a new release candidate, never directly 82into a final release. 83 84 85=item Stable/Maint release (MAINT). 86 87A release with an even version number, and subversion number > 0, such as 885.14.1 or 5.14.2. 89 90At this point you should have a working release candidate with few or no 91changes since. 92 93It's essentially the same procedure as for making a release candidate, but 94with a whole bunch of extra post-release steps. 95 96Note that for a maint release there are two versions of this guide to 97consider: the one in the maint branch, and the one in blead. Which one to 98use is a fine judgement. The blead one will be most up-to-date, while 99it might describe some steps or new tools that aren't applicable to older 100maint branches. It is probably best to review both versions of this 101document, but to most closely follow the steps in the maint version. 102 103=item A blead point release (BLEAD-POINT) 104 105A release with an odd version number, such as 5.15.0 or 5.15.1. 106 107This isn't for production, so it has less stability requirements than for 108other release types, and isn't preceded by RC releases. Other than that, 109it is similar to a MAINT release. 110 111=item Blead final release (BLEAD-FINAL) 112 113A release with an even version number, and subversion number == 0, such as 1145.14.0. That is to say, it's the big new release once per year. 115 116It's essentially the same procedure as for making a release candidate, but 117with a whole bunch of extra post-release steps, even more than for MAINT. 118 119=back 120 121=for checklist begin 122 123=head2 Prerequisites 124 125Before you can make an official release of perl, there are a few 126hoops you need to jump through: 127 128=head3 PAUSE account with pumpkin status 129 130Make sure you have a PAUSE account suitable for uploading a perl release. 131If you don't have a PAUSE account, then request one: 132 133 https://pause.perl.org/pause/query?ACTION=request_id 134 135Check that your account is allowed to upload perl distros: go to 136L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that 137your PAUSE ID is listed there. If not, ask Andreas KE<0xf6>nig to add your ID 138to the list of people allowed to upload something called perl. You can find 139Andreas' email address at: 140 141 https://pause.perl.org/pause/query?ACTION=pause_04imprint 142 143=head3 GitHub access 144 145You will need a working C<git> installation, checkout of the perl 146git repository and perl commit bit. For information about working 147with perl and git, see F<pod/perlgit.pod>. 148 149If you are not yet a perl committer, you won't be able to make a 150release. You will need to have a GitHub account (if you don't have one) 151and contact the Steering Council with your username to get membership in the 152L<< Perl-Releasers|https://github.com/orgs/Perl/teams/perl-releasers >> team. 153 154=head3 web-based file share 155 156You will need to be able to share tarballs with #p5p members for 157pre-release testing, and you may wish to upload to PAUSE via URL. 158Make sure you have a way of sharing files, such as a web server or 159file-sharing service. 160 161If you use Dropbox, you can append "raw=1" as a parameter to their usual 162sharing link to allow direct download (albeit with redirects). 163 164=head3 Quotation for release announcement epigraph 165 166You will need a quotation to use as an epigraph to your release announcement. 167It will live forever (along with Perl), so make it a good one. 168 169=head3 Install the previous version of perl 170 171During the testing phase of the release you have created, you will be 172asked to compare the installed files with a previous install. Save yourself 173some time on release day, and have a (clean) install of the previous 174version ready. 175 176=head2 Building a release - advance actions 177 178The work of building a release candidate for an even numbered release 179(BLEAD-FINAL) of perl generally starts several weeks before the first 180release candidate. Some of the following steps should be done regularly, 181but all I<must> be done in the run up to a release. 182 183=head3 dual-life CPAN module synchronisation 184 185To see which core distro versions differ from the current CPAN versions: 186 187 $ ./perl -Ilib Porting/core-cpan-diff -x -a 188 189However, this only checks whether the version recorded in 190F<Porting/Maintainers.pl> differs from the latest on CPAN. It doesn't tell you 191if the code itself has diverged from CPAN. 192 193You can also run an actual diff of the contents of the modules, comparing core 194to CPAN, to ensure that there were no erroneous/extraneous changes that need to 195be dealt with. You do this by not passing the C<-x> option: 196 197 $ ./perl -Ilib Porting/core-cpan-diff -a -o ~/corediffs 198 199Passing C<-u cpan> will probably be helpful, since it limits the search to 200distributions with 'cpan' upstream source. (It's OK for blead upstream to 201differ from CPAN because those dual-life releases usually come I<after> perl 202is released.) 203 204See also the C<-d> and C<-v> options for more detail (and the C<-u> option as 205mentioned above). You'll probably want to use the C<-c cachedir> option to 206avoid repeated CPAN downloads and may want to use C<-m file:///mirror/path> if 207you made a local CPAN mirror. Note that a minicpan mirror won't actually work, 208but can provide a good first pass to quickly get a list of modules which 209definitely haven't changed, to avoid having to download absolutely everything. 210 211For a BLEAD-POINT or BLEAD-FINAL release with 'cpan' upstream, if a CPAN 212release appears to be ahead of blead, then consider updating it (or asking the 213relevant porter to do so). (However, if this is a BLEAD-FINAL release or one of 214the last BLEAD-POINT releases before it and hence blead is in some kind of 215"code freeze" state (e.g. the sequence might be "contentious changes freeze", 216then "user-visible changes freeze" and finally "full code freeze") then any 217CPAN module updates must be subject to the same restrictions, so it may not be 218possible to update all modules until after the BLEAD-FINAL release.) If blead 219contains edits to a 'cpan' upstream module, this is naughty but sometimes 220unavoidable to keep blead tests passing. Make sure the affected file has a 221CUSTOMIZED entry in F<Porting/Maintainers.pl>. 222 223If you are making a MAINT release, run C<core-cpan-diff> on both blead and 224maint, then diff the two outputs. Compare this with what you expect, and if 225necessary, fix things up. For example, you might think that both blead 226and maint are synchronised with a particular CPAN module, but one might 227have some extra changes. 228 229In any case, any cpan-first distribution that is listed as having files 230"Customized for blead" in the output of cpan-core-diff should have requests 231submitted to the maintainer(s) to make a cpan release to catch up with blead. 232 233Additionally, all files listed as "modified" but not "customized for blead" 234should have entries added under the C<CUSTOMIZED> key in 235F<Porting/Maintainers.pl>, as well as checksums updated via: 236 237 cd t; ../perl -I../lib porting/customized.t --regen 238 239=head4 Sync CPAN modules with the corresponding cpanE<sol> distro 240 241In most cases, once a new version of a distribution shipped with core has been 242uploaded to CPAN, the core version thereof can be synchronized automatically 243with the program F<Porting/sync-with-cpan>. (But see the comments at the 244beginning of that program. In particular, it has not yet been exercised on 245Windows as much as it has on Unix-like platforms.) 246 247If, however, F<Porting/sync-with-cpan> does not provide good results, follow 248the steps below. 249 250=over 4 251 252=item * 253 254Fetch the most recent version from CPAN. 255 256=item * 257 258Unpack the retrieved tarball. Rename the old directory; rename the new 259directory to the original name. 260 261=item * 262 263Restore any F<.gitignore> file. This can be done by issuing 264C<git checkout .gitignore> in the F<cpan/Distro> directory. 265 266=item * 267 268Remove files we do not need. That is, remove any files that match the 269entries in C<@IGNORABLE> in F<Porting/Maintainers.pl>, and anything that 270matches the C<EXCLUDED> section of the distro's entry in the C<%Modules> 271hash. 272 273=item * 274 275Restore any files mentioned in the C<CUSTOMIZED> section, using 276C<git checkout>. Make any new customizations if necessary. Also, 277restore any files that are mentioned in C<@IGNORE>, but were checked 278into the repository anyway. 279 280=item * 281 282For any new files in the distro, determine whether they are needed. 283If not, delete them, and list them in either C<EXCLUDED> or C<@IGNORABLE>. 284Otherwise, add them to C<MANIFEST>, and run C<git add> to add the files 285to the repository. 286 287=item * 288 289For any files that are gone, remove them from C<MANIFEST>, and use 290C<git rm> to tell git the files will be gone. 291 292=item * 293 294If the C<MANIFEST> file was changed in any of the previous steps, run 295C<perl Porting/manisort --output MANIFEST.sort; mv MANIFEST.sort MANIFEST>. 296 297=item * 298 299For any files that have an execute bit set, either remove the execute 300bit, or edit F<Porting/exec-bit.txt> 301 302=item * 303 304Run C<make> (or C<nmake> on Windows), see if C<perl> compiles. 305 306=item * 307 308Run the tests for the package. 309 310=item * 311 312Run the tests in F<t/porting> (C<make test_porting>). 313 314=item * 315 316Update the C<DISTRIBUTION> entry in F<Porting/Maintainers.pl>. 317 318=item * 319 320Run a full configure/build/test cycle. 321 322=item * 323 324If everything is ok, commit the changes. 325 326=back 327 328For entries with a non-simple C<FILES> section, or with a C<MAP>, you 329may have to take more steps than listed above. 330 331=head3 Ensure dual-life CPAN module stability 332 333This comes down to: 334 335 for each module that fails its regression tests on $current 336 did it fail identically on $previous? 337 if yes, "SEP" (Somebody Else's Problem, but try to make sure a 338 bug ticket is filed) 339 else work out why it failed (a bisect is useful for this) 340 341 attempt to group failure causes 342 343 for each failure cause 344 is that a regression? 345 if yes, figure out how to fix it 346 (more code? revert the code that broke it) 347 else 348 (presumably) it's relying on something un-or-under-documented 349 should the existing behaviour stay? 350 yes - goto "regression" 351 no - note it in perldelta as a significant bugfix 352 (also, try to inform the module's author) 353 354=head3 monitor smoke tests for failures 355 356Similarly, monitor the smoking of core tests, and try to fix. See 357L<https://tux.nl/perl5/smoke/index.html>, L<https://perl5.test-smoke.org/> 358and L<http://perl.develop-help.com> for a summary. See also 359L<https://www.nntp.perl.org/group/perl.daily-build.reports/> which has 360the raw reports. 361 362Similarly, monitor the smoking of perl for compiler warnings, and try to 363fix. 364 365Additionally both L<Travis CI|https://travis-ci.org/Perl/perl5> and 366L<GitHub Actions|https://github.com/Perl/perl5/actions> smokers run 367automatically. 368 369=for checklist skip BLEAD-POINT 370 371=head3 monitor CPAN testers for failures 372 373For any release except a BLEAD-POINT: Examine the relevant analysis report(s) 374at L<http://analysis.cpantesters.org/beforemaintrelease> to see how the 375impending release is performing compared to previous releases with 376regard to building and testing CPAN modules. 377 378That page accepts a query parameter, C<pair> that takes a pair of 379colon-delimited versions to use for comparison. For example: 380 381L<http://analysis.cpantesters.org/beforemaintrelease?pair=5.20.2:5.22.0%20RC1> 382 383=head3 update perldelta 384 385Get perldelta in a mostly finished state. 386 387Read F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that 388every section it lists is, if necessary, populated and complete. Copy 389edit the whole document. 390 391You won't be able to automatically fill in the "Updated Modules" section until 392after Module::CoreList is updated (as described below in 393L<"update Module::CoreList">). 394 395=head3 Bump the version number 396 397Do not do this yet for a BLEAD-POINT release! You will do this at the end of 398the release process (after building the final tarball, tagging etc). 399 400Increase the version number (e.g. from 5.12.0 to 5.12.1). 401 402For a release candidate for a stable perl, this should happen a week or two 403before the first release candidate to allow sufficient time for testing and 404smoking with the target version built into the perl executable. For 405subsequent release candidates and the final release, it is not necessary to 406bump the version further. 407 408There is a tool to semi-automate this process: 409 410 $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1 411 412Remember that this tool is largely just grepping for '5.10.0' or whatever, 413so it will generate false positives. Be careful not change text like 414"this was fixed in 5.10.0"! 415 416Use git status and git diff to select changes you want to keep. 417 418Be particularly careful with F<INSTALL>, which contains a mixture of 419C<5.10.0>-type strings, some of which need bumping on every release, and 420some of which need to be left unchanged. 421See below in L<"update INSTALL"> for more details. 422 423For the first RC release leading up to a BLEAD-FINAL release, update the 424description of which releases are now "officially" supported in 425F<pod/perlpolicy.pod>. 426 427When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the 428C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version 429you're releasing, unless you're absolutely sure the release you're about to 430make is 100% binary compatible to an earlier release. Note: for BLEAD-POINT 431releases the bump should have already occurred at the end of the previous 432release and this is something you would have to do at the very end. 433When releasing a MAINT perl version, the C<PERL_API_*> constants C<MUST NOT> 434be changed as we aim to guarantee binary compatibility in maint branches. 435 436After editing, regenerate uconfig.h (this must be run on a system with a 437/bin/sh available): 438 439 $ perl regen/uconfig_h.pl 440 441This might not cause any new changes. 442 443You may also need to regen opcodes: 444 445 $ ./perl -Ilib regen/opcode.pl 446 447Test your changes: 448 449 $ git clean -xdf # careful if you don't have local files to keep! 450 $ ./Configure -des -Dusedevel 451 $ make 452 $ make test 453 454Do note that at this stage, porting tests will fail. They will continue 455to fail until you've updated Module::CoreList, as described below. 456 457Commit your changes: 458 459 $ git status 460 $ git diff 461 B<review the delta carefully> 462 463 $ git commit -a -m 'Bump the perl version in various places for 5.x.y' 464 465At this point you may want to compare the commit with a previous bump to 466see if they look similar. See commit f7cf42bb69 for an example of a 467previous version bump. 468 469When the version number is bumped, you should also update Module::CoreList 470(as described below in L<"update Module::CoreList">) to reflect the new 471version number. 472 473=head3 update INSTALL 474 475Review and update INSTALL to account for the change in version number. 476INSTALL for a BLEAD-POINT release should already contain the expected version. 477The lines in F<INSTALL> about "is not binary compatible with" may require a 478correct choice of earlier version to declare incompatibility with. These are 479in the "Changes and Incompatibilities" and "Coexistence with earlier versions 480of perl 5" sections. 481 482Be particularly careful with the section "Upgrading from 5.X.Y or earlier". 483The "X.Y" needs to be changed to the most recent version that we are 484I<not> binary compatible with. 485 486For MAINT and BLEAD-FINAL releases, this needs to refer to the last 487release in the previous development cycle (so for example, for a 5.14.x 488release, this would be 5.13.11). 489 490For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT 491release (so for 5.15.3 this would be 5.15.2). If the last release manager 492followed instructions, this should have already been done after the last 493blead release, so you may find nothing to do here. 494 495=head3 update AUTHORS 496 497The AUTHORS file can be updated by running C<Porting/checkAUTHORS.pl --update> 498The script detects missing authors or committers since the last release using 499a known tag provided by the C<--from=v5.X.Y> argument, and will add missing 500entries to the AUTHORS file. 501 502 $ perl Porting/checkAUTHORS.pl --update --from=v5.X.Y 503 504For MAINT and BLEAD-FINAL releases, C<v5.X.Y> needs to refer to the last 505release in the previous development cycle (so for example, for a 5.14.x 506release, this would be 5.13.11). 507 508For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT 509release (so for 5.15.3 this would be 5.15.2). 510 511Note: It should not be harmful to use a wider range. 512 513Note: If you have uncommitted changes this could cause some warnings, 514and you might like to use the addtional argument C<--to=upstream/blead> 515to use the last known git commit by GitHub. 516 517Review the changes to the AUTHORS file, be sure you are not adding duplicate 518entries or removing any entries, then commit your changes. 519 520 $ git commit -a AUTHORS -m 'Update AUTHORS list for 5.x.y' 521 522=head3 Check copyright years 523 524Check that the copyright years are up to date by running: 525 526 $ pushd t; ../perl -I../lib porting/copyright.t --now 527 528Remedy any test failures by editing README or perl.c accordingly (search for 529the "Copyright"). If updating perl.c, check if the file's own copyright date in 530the C comment at the top needs updating, as well as the one printed by C<-v>. 531 532=head3 Check more build configurations 533 534Try running the full test suite against multiple Perl configurations. Here are 535some sets of Configure flags you can try: 536 537=over 4 538 539=item * 540 541C<-Duseshrplib -Dusesitecustomize> 542 543=item * 544 545C<-Duserelocatableinc> 546 547=item * 548 549C<-Dusethreads> 550 551=back 552 553If you have multiple compilers on your machine, you might also consider 554compiling with C<-Dcc=$other_compiler>. 555 556You can also consider pushing the repo to GitHub where Travis CI is enabled 557which would smoke different flavors of Perl for you. 558 559=head3 update perlport 560 561L<perlport> has a section currently named I<Supported Platforms> that 562indicates which platforms are known to build in the current release. 563If necessary update the list and the indicated version number. 564 565=head3 check a readonly build 566 567Even before other prep work, follow the steps in L</build the tarball> and test 568it locally. Because a perl source tarballs sets many files read-only, it could 569test differently than tests run from the repository. After you're sure 570permissions aren't a problem, delete the generated directory and tarballs. 571 572 573=head2 Building a release - on the day 574 575This section describes the actions required to make a release 576that are performed near to, or on the actual release day. 577 578=head3 re-check earlier actions 579 580Review all the actions in the previous section, 581L<"Building a release - advance actions"> to ensure they are all done and 582up-to-date. 583 584=head3 create a release branch 585 586For BLEAD-POINT releases, making a release from a release branch avoids the 587need to freeze blead during the release. This is less important for 588BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in 589those cases. Create the branch by running 590 591 git checkout -b release-5.xx.yy 592 593=head3 build a clean perl 594 595Make sure you have a gitwise-clean perl directory (no modified files, 596unpushed commits etc): 597 598 $ git status 599 $ git clean -dxf 600 601then configure and build perl so that you have a Makefile and porting tools: 602 603 $ ./Configure -Dusedevel -des && make 604 605=head3 Check module versions 606 607For each Perl release since the previous release of the current branch, check 608for modules that have identical version numbers but different contents by 609running: 610 611 $ ./perl -Ilib Porting/cmpVERSION.pl --tag=v5.X.YY 612 613(This is done automatically by F<t/porting/cmp_version.t> for the previous 614release of the current branch, but not for any releases from other branches.) 615 616Any modules that fail will need a version bump, plus a nudge to the upstream 617maintainer for 'cpan' upstream modules. 618 619=head3 update Module::CoreList 620 621=head4 Bump Module::CoreList* $VERSIONs 622 623If necessary, bump C<$VERSION> (there's no need to do this 624for every RC; in RC1, bump the version to a new clean number that will 625appear in the final release, and leave as-is for the later RCs and final). 626It may also happen that C<Module::CoreList> has been modified in blead, and 627hence has a new version number already. (But make sure it is not the same 628number as a CPAN release.) 629 630C<$Module::CoreList::Utils::VERSION> should always be equal to 631C<$Module::CoreList::VERSION>. If necessary, bump those two versions to match 632before proceeding. 633 634Once again, the files to modify are: 635 636=over 4 637 638=item * 639 640F<dist/Module-CoreList/lib/Module/CoreList.pm> 641 642=item * 643 644F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> 645 646=back 647 648=head4 Update C<Module::CoreList> with module version data for the new release. 649 650Note that if this is a MAINT release, you should run the following actions 651from the maint branch, but commit the C<CoreList.pm> changes in 652I<blead> and subsequently cherry-pick any releases since the last 653maint release and then your recent commit. XXX need a better example 654 655[ Note that the procedure for handling Module::CoreList in maint branches 656is a bit complex, and the RMG currently don't describe a full and 657workable approach. The main issue is keeping Module::CoreList 658and its version number synchronised across all maint branches, blead and 659CPAN, while having to bump its version number for every RC release. 660See this brief p5p thread: 661 662 Message-ID: <20130311174402.GZ2294@iabyn.com> 663 664If you can devise a workable system, feel free to try it out, and to 665update the RMG accordingly! 666 667DAPM May 2013 ] 668 669F<corelist.pl> uses www.cpan.org to verify information about dual-lived 670modules on CPAN. It can use a full, local CPAN mirror and/or fall back 671on HTTP::Tiny to fetch package metadata remotely. 672 673(If you'd prefer to have a full CPAN mirror, see 674L<https://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN>) 675 676Change to your perl checkout, and if necessary, 677 678 $ make 679 680Then, If you have a local CPAN mirror, run: 681 682 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror 683 684Otherwise, run: 685 686 $ ./perl -Ilib Porting/corelist.pl cpan 687 688This will chug for a while, possibly reporting various warnings about 689badly-indexed CPAN modules unrelated to the modules actually in core. 690Assuming all goes well, it will update 691F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly 692F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>. 693 694Check those files over carefully: 695 696 $ git diff dist/Module-CoreList/lib/Module/CoreList.pm 697 $ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm 698 699=head4 Bump version in Module::CoreList F<Changes> 700 701Also edit Module::CoreList's new version number in its F<Changes> file. 702This file is F<dist/Module-CoreList/Changes>. 703(BLEAD-POINT releases should have had this done already as a post-release 704action from the last commit.) 705 706=head4 Add Module::CoreList version bump to perldelta 707 708Add a perldelta entry for the new Module::CoreList version. You only 709need to do this if you want to add notes about the changes included 710with this version of Module::CoreList. Otherwise, its version bump 711will be automatically filled in below in L</finalize perldelta>. 712 713=for checklist skip RC 714 715=head4 Update C<%Module::CoreList::released> 716 717For any release except an RC: Update this version's entry in the C<%released> 718hash with today's date. 719 720=head4 Commit Module::CoreList changes 721 722Finally, commit the new version of Module::CoreList: 723(unless this is for MAINT; in which case commit it to blead first, then 724cherry-pick it back). 725 726 $ git commit -m 'Update Module::CoreList for 5.x.y' \ 727 dist/Module-CoreList/Changes \ 728 dist/Module-CoreList/lib/Module/CoreList.pm \ 729 dist/Module-CoreList/lib/Module/CoreList/Utils.pm 730 731=head4 Rebuild and test 732 733Build and test to get the changes into the currently built lib directory and to 734ensure all tests are passing. 735 736=head3 finalize perldelta 737 738Finalize the perldelta. In particular, fill in the Acknowledgements 739section, which can be generated with something like: 740 741 $ perl Porting/acknowledgements.pl v5.15.0..HEAD 742 743Fill in the "New/Updated Modules" sections now that Module::CoreList is 744updated: 745 746 $ ./perl -Ilib Porting/corelist-perldelta.pl \ 747 --mode=update pod/perldelta.pod 748 749For a MAINT release use something like this instead: 750 751 $ ./perl -Ilib Porting/corelist-perldelta.pl 5.020001 5.020002 \ 752 --mode=update pod/perldelta.pod 753 754Ideally, also fill in a summary of the major changes to each module for which 755an entry has been added by F<corelist-perldelta.pl>. 756 757Re-read the perldelta to try to find any embarrassing typos and thinkos; 758remove any C<TODO> or C<XXX> flags; update the "Known Problems" section 759with any serious issues for which fixes are not going to happen now; and 760run through pod and spell checkers, e.g. 761 762 $ podchecker -warnings -warnings pod/perldelta.pod 763 $ spell pod/perldelta.pod 764 $ aspell list < pod/perldelta.pod | sort -u 765 766Also, you may want to generate and view an HTML version of it to check 767formatting, e.g. 768 769 $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > \ 770 ~/perldelta.html 771 772You should add pod links for GitHub issue references thusly: 773 774 $ perl -p -i -e'BEGIN{undef $/}; s{(GH\s+#)(\d+)}{L<$1$2|https://github.com/Perl/perl5/issues/$2>}mg' pod/perldelta.pod 775 776If you make changes, be sure to commit them. 777 778=for checklist skip BLEAD-POINT MAINT RC 779 780=head3 remove stale perldeltas 781 782For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas 783from the BLEAD-POINT releases since the previous BLEAD-FINAL should have 784now been consolidated into the current perldelta, and hence are now just 785useless clutter. They can be removed using: 786 787 $ git rm <file1> <file2> ... 788 789For example, for RC0 of 5.16.0: 790 791 $ cd pod 792 $ git rm perldelta515*.pod 793 794=for checklist skip BLEAD-FINAL BLEAD-POINT 795 796=head3 add recent perldeltas 797 798For the first RC for a MAINT release, copy in any recent perldeltas from 799blead that have been added since the last release on this branch. This 800should include any recent maint releases on branches older than your one, 801but not newer. For example if you're producing a 5.14.x release, copy any 802perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from 8035.16.x or higher. Remember to 804 805 $ git add <file1> <file2> ... 806 807=head3 update and commit perldelta files 808 809If you have added or removed any perldelta files via the previous two 810steps, then edit F<pod/perl.pod> to add/remove them from its table of 811contents, then run F<Porting/pod_rules.pl> to propagate your changes there 812into all the other files that mention them (including F<MANIFEST>). You'll 813need to C<git add> the files that it changes. 814 815Then build a clean perl and do a full test 816 817 $ git status 818 $ git clean -dxf 819 $ ./Configure -Dusedevel -des 820 $ make 821 $ make test 822 823Once all tests pass, commit your changes. 824 825=head3 final check of perldelta placeholders 826 827Check for any 'XXX' leftover section in the perldelta. 828Either fill them or remove these sections appropriately. 829 830 $ git grep XX pod/perldelta.pod 831 832=head3 build a clean perl 833 834If you skipped the previous step (adding/removing perldeltas), 835again, make sure you have a gitwise-clean perl directory (no modified files, 836unpushed commits etc): 837 838 $ git status 839 $ git clean -dxf 840 841then configure and build perl so that you have a Makefile and porting tools: 842 843 $ ./Configure -Dusedevel -des && make 844 845=for checklist skip BLEAD-FINAL BLEAD-POINT 846 847=head3 synchronise from blead's perlhist.pod 848 849For the first RC for a MAINT release, copy in the latest 850F<pod/perlhist.pod> from blead; this will include details of newer 851releases in all branches. In theory, blead's version should be a strict 852superset of the one in this branch, but it's probably safest to examine the 853changes first, to ensure that there's nothing in this branch that was 854forgotten from blead. An easy way to do that is with C<< git checkout -p >>, 855to selectively apply any changes from the blead version to your current 856branch: 857 858 $ git fetch origin 859 $ git checkout -p origin/blead pod/perlhist.pod 860 $ git commit -m 'sync perlhist from blead' pod/perlhist.pod 861 862=head3 update perlhist.pod 863 864Add an entry to F<pod/perlhist.pod> with the release date, e.g.: 865 866 David 5.10.1 2009-Aug-06 867 868List yourself in the left-hand column, and if this is the first release 869that you've ever done, make sure that your name is listed in the section 870entitled C<THE KEEPERS OF THE PUMPKIN>. 871 872I<If you're making a BLEAD-FINAL release>, also update the "SELECTED 873RELEASE SIZES" section with the output of 874F<Porting/perlhist_calculate.pl>. 875 876Be sure to commit your changes: 877 878 $ git commit -m 'add new release to perlhist' pod/perlhist.pod 879 880=for checklist skip BLEAD-POINT 881 882=head3 update patchlevel.h 883 884I<You MUST SKIP this step for a BLEAD-POINT release> 885 886Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is 887a final release, remove it. For example: 888 889 static const char * const local_patches[] = { 890 NULL 891 + ,"RC1" 892 #ifdef PERL_GIT_UNCOMMITTED_CHANGES 893 ,"uncommitted-changes" 894 #endif 895 896Be sure to commit your change: 897 898 $ git commit -m 'bump version to RCnnn' patchlevel.h 899 900=head3 run makemeta to update META files 901 902 $ ./perl -Ilib Porting/makemeta 903 904Be sure to commit any changes (if applicable): 905 906 $ git status # any changes? 907 $ git commit -m 'Update META files' META.* 908 909=head3 build, test and check a fresh perl 910 911Build perl, then make sure it passes its own test suite, and installs: 912 913 $ git clean -xdf 914 $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest 915 916 # or if it's an odd-numbered version: 917 $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest 918 919 $ make test install 920 921Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and 922C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected, 923especially as regards version numbers, patch and/or RC levels, and @INC 924paths. Note that as they have been built from a git working 925directory, they will still identify themselves using git tags and 926commits. (Note that for an odd-numbered version, perl will install 927itself as C<perl5.x.y>). C<perl -v> will identify itself as: 928 929 This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef)) 930 931where 5.X.Z is the latest tag, NNN the number of commits since this tag, 932and C<< deadbeef >> commit of that tag. 933 934Then delete the temporary installation. 935 936=head3 create the release tag 937 938Create the tag identifying this release (e.g.): 939 940 $ git tag v5.11.0 -m 'First release of the v5.11 series!' 941 942It is B<VERY> important that from this point forward, you not push 943your git changes to the Perl master repository. If anything goes 944wrong before you publish your newly-created tag, you can delete 945and recreate it. Once you push your tag, we're stuck with it 946and you'll need to use a new version number for your release. 947 948=head3 build the tarball 949 950Before you run the following, you might want to install 7-Zip (the 951C<p7zip-full> package under Debian or the C<p7zip> port on MacPorts) or 952the AdvanceCOMP suite (e.g. the C<advancecomp> package under Debian, 953or the C<advancecomp> port on macports - 7-Zip on Windows is the 954same code as AdvanceCOMP, so Windows users get the smallest files 955first time). These compress about 5% smaller than gzip and bzip2. 956Over the lifetime of your distribution this will save a lot of 957people a small amount of download time and disk space, which adds 958up. 959 960In order to produce the C<xz> tarball, XZ Utils are required. The C<xz> 961utility is included with most modern UNIX-type operating systems and 962is available for Cygwin. A Windows port is available from 963L<https://tukaani.org/xz/>. 964 965B<IMPORTANT>: if you are on OS X, you must export C<COPYFILE_DISABLE=1> 966to prevent OS X resource files from being included in your tarball. After 967creating the tarball following the instructions below, inspect it to ensure 968you don't have files like F<._foobar>. 969 970Create a tarball. Use the C<-s> option to specify a suitable suffix for 971the tarball and directory name: 972 973 $ cd root/of/perl/tree 974 $ make distclean # make sure distclean works 975 $ git clean -xdf # make sure perl and git agree on files 976 # git clean should not output anything! 977 $ git status --ignored # and there's nothing lying around 978 979 $ perl Porting/makerel -x -s RC1 # for a release candidate 980 $ perl Porting/makerel -x # for the release itself 981 982This creates the directory F<../perl-x.y.z-RC1> or similar, copies all 983the MANIFEST files into it, sets the correct permissions on them, then 984tars it up as F<../perl-x.y.z-RC1.tar.gz>. The C<-x> also produces a 985C<tar.xz> file. 986 987If you're getting your tarball suffixed with -uncommitted and you're sure 988your changes were all committed, you can override the suffix with: 989 990 $ perl Porting/makerel -x -s '' 991 992XXX if we go for extra tags and branches stuff, then add the extra details 993here 994 995Finally, clean up the temporary directory, e.g. 996 997 $ rm -rf ../perl-x.y.z-RC1 998 999=head3 test the tarball 1000 1001Once you have a tarball it's time to test the tarball (not the repository). 1002 1003=head4 Copy the tarball to a web server 1004 1005Copy the tarballs (.gz and .xz) to a web server somewhere you have access to. 1006 1007=head4 Download the tarball to another machine and unpack it 1008 1009Download the tarball to some other machine. For a release candidate, 1010you really want to test your tarball on two or more different platforms 1011and architectures. 1012 1013=head4 Ask #p5p to test the tarball on different platforms 1014 1015Once you've verified the tarball can be downloaded and unpacked, 1016ask the #p5p IRC channel on irc.perl.org for volunteers to test the 1017tarballs on whatever platforms they can. 1018 1019If you're not confident in the tarball, you can defer this step until after 1020your own tarball testing, below. 1021 1022=head4 Check that F<Configure> works 1023 1024Check that basic configuration and tests work on each test machine: 1025 1026 $ ./Configure -des && make all minitest test 1027 1028 # Or for a development release: 1029 $ ./Configure -Dusedevel -des && make all minitest test 1030 1031=head4 Run the test harness and install 1032 1033Check that the test harness and install work on each test machine: 1034 1035 $ make distclean 1036 $ ./Configure -des -Dprefix=/install/path && \ 1037 make all test_harness install 1038 $ cd /install/path 1039 1040(Remember C<-Dusedevel> above, for a development release.) 1041 1042=head4 Check C<perl -v> and C<perl -V> 1043 1044Check that the output of C<perl -v> and C<perl -V> are as expected, 1045especially as regards version numbers, patch and/or RC levels, and @INC 1046paths. 1047 1048Note that the results may be different without a F<.git/> directory, 1049which is why you should test from the tarball. 1050 1051=head4 Run the Installation Verification Procedure utility 1052 1053 $ ./perl -Ilib ./utils/perlivp 1054 # Or, perhaps: 1055 $ ./perl5.x.y ./utils/perlivp5.x.y 1056 ... 1057 All tests successful. 1058 $ 1059 1060=head4 Compare the installed paths to the last release 1061 1062Compare the pathnames of all installed files with those of the previous 1063release (i.e. against the last installed tarball on this branch which you 1064have previously verified using this same procedure). In particular, look 1065for files in the wrong place, or files no longer included which should be. 1066For example, suppose the about-to-be-released version is 5.10.1 and the 1067previous is 5.10.0: 1068 1069 cd installdir-5.10.0/ 1070 find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1 1071 cd installdir-5.10.1/ 1072 find . -type f | sort > /tmp/f2 1073 diff -u /tmp/f[12] 1074 1075=head4 Disable C<local::lib> if it's turned on 1076 1077If you're using C<local::lib>, you should reset your environment before 1078performing these actions: 1079 1080 $ unset PERL5LIB PERL_MB_OPT PERL_LOCAL_LIB_ROOT PERL_MM_OPT 1081 1082=head4 Bootstrap the CPAN client 1083 1084Bootstrap the CPAN client on the clean install: 1085 1086 $ bin/cpan 1087 1088 # Or, perhaps: 1089 $ bin/cpan5.xx.x 1090 1091=head4 Install the Inline module with CPAN and test it 1092 1093Try installing a popular CPAN module that's reasonably complex and that 1094has dependencies; for example: 1095 1096 CPAN> install Inline::C 1097 CPAN> quit 1098 1099Check that your perl can run this: 1100 1101 $ bin/perl -Ilib -lwe "use Inline C => q[int f() { return 42;}]; print f" 1102 42 1103 $ 1104 1105=head4 Make sure that perlbug works 1106 1107Test L<perlbug> with the following: 1108 1109 $ bin/perlbug 1110 ... 1111 Subject: test bug report 1112 Local perl administrator [yourself]: 1113 Editor [vi]: 1114 Module: 1115 Category [core]: 1116 Severity [low]: 1117 (edit report) 1118 Action (Send/Display/Edit/Subject/Save to File): f 1119 Name of file to save message in [perlbug.rep]: 1120 Action (Send/Display/Edit/Subject/Save to File): Q 1121 1122and carefully examine the output (in F<perlbug.rep]>), especially 1123the "Locally applied patches" section. 1124 1125=for checklist skip BLEAD-POINT 1126 1127=head3 monitor smokes 1128 1129XXX This is probably irrelevant if working on a release branch, though 1130MAINT or RC might want to push a smoke branch and wait. 1131 1132Wait for the smoke tests to catch up with the commit which this release is 1133based on (or at least the last commit of any consequence). 1134 1135Then check that the smoke tests pass (particularly on Win32). If not, go 1136back and fix things. 1137 1138Note that for I<BLEAD-POINT> releases this may not be practical. It takes a 1139long time for the smokers to catch up, especially the Win32 1140smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL> 1141releases, but for I<BLEAD-POINT> releases sometimes the best you can do is 1142to plead with people on IRC to test stuff on their platforms, fire away, 1143and then hope for the best. 1144 1145=head3 upload to PAUSE 1146 1147Once smoking is okay, upload it to PAUSE. This is the point of no return. 1148If anything goes wrong after this point, you will need to re-prepare 1149a new release with a new minor version or RC number. 1150 1151 https://pause.perl.org/ 1152 1153(Log in, then select 'Upload a file to CPAN') 1154 1155If your workstation is not connected to a high-bandwidth, 1156high-reliability connection to the Internet, you should probably use the 1157"GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the 1158new release from wherever you put it for testers to find it. This will 1159eliminate anxious gnashing of teeth while you wait to see if your 116015 megabyte HTTP upload successfully completes across your slow, twitchy 1161cable modem. 1162 1163I<Remember>: if your upload is partially successful, you 1164may need to contact a PAUSE administrator or even bump the version of perl. 1165 1166Upload the .gz and .xz versions of the tarball. 1167 1168Note: You can also use the command-line utility to upload your tarballs, if 1169you have it configured: 1170 1171 cpan-upload perl-5.X.Y.tar.gz 1172 cpan-upload perl-5.X.Y.tar.xz 1173 1174Do not proceed any further until you are sure that your tarballs are on CPAN. 1175Check your authors directory metacpan.org to confirm that your uploads have 1176been successful. 1177 1178 https://metacpan.org/author/YOUR_PAUSE_ID 1179 1180=for checklist skip RC BLEAD-POINT 1181 1182=head3 wait for indexing 1183 1184I<You MUST SKIP this step for RC and BLEAD-POINT> 1185 1186Wait until you receive notification emails from the PAUSE indexer 1187confirming that your uploads have been received. IMPORTANT -- you will 1188probably get an email that indexing has failed, due to module permissions. 1189This is considered normal. 1190 1191=for checklist skip BLEAD-POINT 1192 1193=head3 disarm patchlevel.h 1194 1195I<You MUST SKIP this step for BLEAD-POINT release> 1196 1197Disarm the F<patchlevel.h> change; for example, 1198 1199 static const char * const local_patches[] = { 1200 NULL 1201 - ,"RC1" 1202 #ifdef PERL_GIT_UNCOMMITTED_CHANGES 1203 ,"uncommitted-changes" 1204 #endif 1205 1206Be sure to commit your change: 1207 1208 $ git commit -m 'disarm RCnnn bump' patchlevel.h 1209 1210=head3 announce to p5p 1211 1212Mail perl5-porters@perl.org to announce your new release, with a quote you prepared earlier. 1213Get the SHA1 digests from the PAUSE email responses. 1214 1215Use the template at Porting/release_announcement_template.txt 1216 1217Send a carbon copy to C<noc@metacpan.org> 1218 1219=head3 merge release branch back to blead 1220 1221Merge the (local) release branch back into master now, and delete it. 1222 1223 git checkout blead 1224 git pull 1225 git merge release-5.xx.yy 1226 git push 1227 git branch -d release-5.xx.yy 1228 1229Note: The merge will create a merge commit if other changes have been pushed 1230to blead while you've been working on your release branch. Do NOT rebase your 1231branch to avoid the merge commit (as you might normally do when merging a 1232small branch into blead) since doing so will invalidate the tag that you 1233created earlier. 1234 1235=head3 publish the release tag 1236 1237Now that you've shipped the new perl release to PAUSE and pushed your changes 1238to the Perl master repository, it's time to publish the tag you created 1239earlier too (e.g.): 1240 1241 $ git push origin tag v5.11.0 1242 1243=head3 update epigraphs.pod 1244 1245Add your quote to F<Porting/epigraphs.pod> and commit it. 1246You can include the customary link to the release announcement even before your 1247message reaches the web-visible archives by looking for the X-List-Archive 1248header in your message after receiving it back via perl5-porters. 1249 1250=head3 blog about your epigraph 1251 1252If you have a blog, please consider writing an entry in your blog explaining 1253why you chose that particular quote for your epigraph. 1254 1255=head3 update the link to the latest perl on perlweb 1256 1257Submit a pull request to L<https://github.com/perlorg/perlweb> to update the 1258link in F<docs/dev/perl5/index.html> to point to your release. 1259 1260=for checklist skip RC 1261 1262=head3 Release schedule 1263 1264I<You MUST SKIP this step for RC> 1265 1266Tick the entry for your release in F<Porting/release_schedule.pod>. 1267 1268=for checklist skip RC 1269 1270=head3 Module::CoreList nagging 1271 1272I<You MUST SKIP this step for RC> 1273 1274Remind the current maintainer of C<Module::CoreList> to push a new release 1275to CPAN. 1276 1277=for checklist skip RC 1278 1279=head3 new perldelta 1280 1281I<You MUST SKIP this step for RC> 1282 1283Create a new perldelta. 1284 1285=over 4 1286 1287=item * 1288 1289Confirm that you have a clean checkout with no local changes. 1290 1291=item * 1292 1293Run: 1294 perl Porting/new-perldelta.pl 1295 1296=item * 1297 1298Run the C<git add> commands it outputs to add new and modified files. 1299 1300=item * 1301 1302Verify that the build still works, by running C<./Configure> and 1303C<make test_porting>. (On Win32 use the appropriate make utility). 1304 1305=item * 1306 1307If F<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>, 1308run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail. 1309Skip to the end of its test output to see the options it offers you. 1310 1311=item * 1312 1313When C<make test_porting> passes, commit the new perldelta. 1314 1315 git commit -m'new perldelta for 5.X.Y' 1316 1317=back 1318 1319At this point you may want to compare the commit with a previous bump to 1320see if they look similar. See commit ba03bc34a4 for an example of a 1321previous version bump. 1322 1323=for checklist skip MAINT RC 1324 1325=head3 bump version 1326 1327I<You MUST SKIP this step for RC and MAINT> 1328 1329If this was a BLEAD-FINAL release (i.e. the first release of a new maint 1330series, 5.x.0 where x is even), then bump the version in the blead branch 1331in git, e.g. 5.12.0 to 5.13.0. 1332 1333First, add a new feature bundle to F<regen/feature.pl>, initially by just 1334copying the exiting entry, and bump the file's $VERSION (after the __END__ 1335marker); e.g. 1336 1337 "5.14" => [qw(switch say state unicode_strings)], 1338 + "5.15" => [qw(switch say state unicode_strings)], 1339 1340Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>. 1341 1342Then follow the section L<"Bump the version number"> to bump the version 1343in the remaining files and test and commit. 1344 1345If this was a BLEAD-POINT release, then just follow the section 1346L<"Bump the version number">. 1347 1348After bumping the version, follow the section L<"update INSTALL"> to 1349ensure all version number references are correct. 1350 1351(Note: The version is NOT bumped immediately after a MAINT release in order 1352to avoid confusion and wasted time arising from bug reports relating to 1353"intermediate versions" such as 5.20.1-and-a-bit: If the report is caused 1354by a bug that gets fixed in 5.20.2 and this intermediate version already 1355calls itself 5.20.2 then much time can be wasted in figuring out why there 1356is a failure from something that "should have been fixed". If the bump is 1357late then there is a much smaller window of time for such confusing bug 1358reports to arise. (The opposite problem -- trying to figure out why there 1359*is* a bug in something calling itself 5.20.1 when in fact the bug was 1360introduced later -- shouldn't arise for MAINT releases since they should, 1361in theory, only contain bug fixes but never regressions.)) 1362 1363=head3 clean build and test 1364 1365Run a clean build and test to make sure nothing obvious is broken. This is 1366very important, as commands run after this point must be run using the perl 1367executable built with the bumped version number. 1368 1369 $ git clean -xdf 1370 $ ./Configure -des -Dusedevel 1371 $ make 1372 $ make test 1373 1374In particular, F<Porting/perldelta_template.pod> is intentionally exempted 1375from podchecker tests, to avoid false positives about placeholder text. 1376However, once it's copied to F<pod/perldelta.pod> the contents can now 1377cause test failures. Problems should be resolved by doing one of the 1378following: 1379 1380=over 1381 1382=item 1 1383 1384Replace placeholder text with correct text. 1385 1386=item 2 1387 1388If the problem is from a broken placeholder link, you can add it to the 1389array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines 1390containing such links should be marked with C<XXX> so that they get 1391cleaned up before the next release. 1392 1393=item 3 1394 1395Following the instructions output by F<t/porting/podcheck.t> on how to 1396update its exceptions database. 1397 1398=back 1399 1400=head3 push commits 1401 1402Finally, push any commits done above. 1403 1404 $ git push origin .... 1405 1406=for checklist skip BLEAD-POINT MAINT RC 1407 1408=head3 create maint branch 1409 1410I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT> 1411 1412If this was a BLEAD-FINAL release (i.e. the first release of a new maint 1413series, 5.x.0 where x is even), then create a new maint branch based on 1414the commit tagged as the current release. 1415 1416Assuming you're using git 1.7.x or newer: 1417 1418 $ git checkout -b maint-5.12 v5.12.0 1419 $ git push origin -u maint-5.12 1420 1421 1422=for checklist skip BLEAD-POINT MAINT RC 1423 1424=head3 make the maint branch available in the APC 1425 1426Clone the new branch into /srv/gitcommon/branches on camel so the APC will 1427receive its changes. 1428 1429 $ git clone --branch maint-5.14 /gitroot/perl.git \ 1430 ? /srv/gitcommon/branches/perl-5.14.x 1431 $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x 1432 1433And nag the sysadmins to make this directory available via rsync. 1434 1435XXX Who are the sysadmins? Contact info? 1436 1437=for checklist skip BLEAD-POINT RC 1438 1439=head3 copy perldelta.pod to blead 1440 1441I<You MUST SKIP this step for RC, BLEAD-POINT> 1442 1443Copy the perldelta.pod for this release into blead; for example: 1444 1445 $ cd ..../blead 1446 $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod #for example 1447 $ git add pod/perl5101delta.pod 1448 1449Don't forget to set the NAME correctly in the new file (e.g. perl5101delta 1450rather than perldelta). 1451 1452Edit F<pod/perl.pod> to add an entry for the file, e.g.: 1453 1454 perl5101delta Perl changes in version 5.10.1 1455 1456Then rebuild various files: 1457 1458 $ perl Porting/pod_rules.pl 1459 1460Finally, commit and push: 1461 1462 $ git commit -a -m 'add perlXXXdelta' 1463 $ git push origin .... 1464 1465=for checklist skip BLEAD-POINT 1466 1467=head3 copy perlhist.pod entries to blead 1468 1469Make sure any recent F<pod/perlhist.pod> entries are copied to 1470F<perlhist.pod> on blead. e.g. 1471 1472 5.8.9 2008-Dec-14 1473 1474=head3 Relax! 1475 1476I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some 1477much-needed rest and relaxation>. 1478 1479Thanks for releasing perl! 1480 1481=head2 Building a release - the day after 1482 1483=for checklist skip BLEAD-FINAL MAINT RC 1484 1485=head3 update Module::CoreList 1486 1487I<After a BLEAD-POINT release only> 1488 1489After Module::CoreList has shipped to CPAN by the maintainer, update 1490Module::CoreList in the source so that it reflects the new blead 1491version number: 1492 1493=over 4 1494 1495=item * 1496 1497Update F<Porting/Maintainers.pl> to list the new DISTRIBUTION on CPAN, 1498which should be identical to what is currently in blead. 1499 1500=item * 1501 1502Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm> 1503and F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>. 1504 1505=item * 1506 1507If you have a local CPAN mirror, run: 1508 1509 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror 1510 1511Otherwise, run: 1512 1513 $ ./perl -Ilib Porting/corelist.pl cpan 1514 1515This will update F<dist/Module-CoreList/lib/Module/CoreList.pm> and 1516F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before, 1517but this time adding new sections for the next BLEAD-POINT release. 1518 1519=item * 1520 1521Add the new $Module::CoreList::VERSION to 1522F<dist/Module-CoreList/Changes>. 1523 1524=item * 1525 1526Remake perl to get your changed .pm files propagated into F<lib/> and 1527then run at least the F<dist/Module-CoreList/t/*.t> tests and the 1528test_porting makefile target to check that they're ok. 1529 1530=item * 1531 1532Run 1533 1534 $ ./perl -Ilib -MModule::CoreList \ 1535 -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"' 1536 1537and check that it outputs "ok" to prove that Module::CoreList now knows 1538about blead's current version. 1539 1540=item * 1541 1542Commit and push your changes. 1543 1544=back 1545 1546=head3 check tarball availability 1547 1548Check various website entries to make sure the that tarball has appeared 1549and is properly indexed: 1550 1551=over 4 1552 1553=item * 1554 1555Check your author directory under L<https://www.cpan.org/authors/id/> 1556to ensure that the tarballs are available on the website. 1557 1558=item * 1559 1560Check F</src> on CPAN (on a fast mirror) to ensure that links to 1561the new tarballs have appeared: There should be links in F</src/5.0> 1562(which is accumulating all new versions), and (for BLEAD-FINAL and 1563MAINT only) an appropriate mention in F</src/README.html> (which describes 1564the latest versions in each stable branch, with links). 1565 1566The F</src/5.0> links should appear automatically, some hours after upload. 1567If they don't, or the F</src> description is inadequate, 1568ask Ask <ask@perl.org>. 1569 1570=item * 1571 1572Check L<https://www.cpan.org/src/> to ensure that the F</src> updates 1573have been correctly mirrored to the website. 1574If they haven't, ask Ask <ask@perl.org>. 1575 1576=item * 1577 1578Check L<https://metacpan.org> to see if it has indexed the distribution. 1579It should be visible at a URL like C<https://metacpan.org/release/DAPM/perl-5.10.1>. 1580 1581=back 1582 1583=head3 update release manager's guide 1584 1585Go over your notes from the release (you did take some, right?) and update 1586F<Porting/release_managers_guide.pod> with any fixes or information that 1587will make life easier for the next release manager. 1588 1589=for checklist end 1590 1591=head1 SOURCE 1592 1593Based on 1594L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html>, 1595plus a whole bunch of other sources, including private correspondence. 1596 1597=cut 1598 1599