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