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