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