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