Porting/release_managers_guide.pod

   1
   2 =head1 NAME
   3
   4 release_managers_guide - Releasing a new version of perl 5.x
   5
   6 XXX as of Jul 2009, this file is still a work-in-progress - DAPM
   7
   8 =head1 SYNOPSIS
   9
  10 This document describes the series of tasks required - some automatic, some
  11 manual - to produce a perl release of some description, be that a snaphot,
  12 release candidate, or final release.
  13
  14 The release process is primarily executed by the current pumpking.
  15
  16 This document both helps as a check-list for the pumpking and is
  17 a base for ideas on how the various tasks could be automated or
  18 distributed.
  19
  20 The outline of a release cycle is as follows:
  21
  22     (5.10.1 is released, and post-release action have been done)
  23
  24     ...time passes...
  25
  26     an occasional snapshot is released, that still identifies itself as
  27         5.10.1
  28
  29     ...time passes...
  30
  31     a few weeks before the release, a number of steps are performed,
  32         including bumping the version to 5.10.2
  33
  34     perl-5.10.2-RC1 is released
  35
  36     perl-5.10.2 is released
  37
  38     post-release actions are performed, including creating new
  39         perl5103delta.pod
  40
  41     ... the cycle continues ...
  42
  43 =head1 DETAILS
  44
  45
  46 =head2 Building a snapshot
  47
  48 A snapshot is intended to encourage in-depth testing from time-to-time,
  49 for example after a key point in the stabilisation of a branch. It
  50 requires less steps than a full release, and the version number of perl in
  51 the tarball will usually still be the old one.
  52
  53 =over 4
  54
  55 =item *
  56
  57 As there are no regular smokes [ XXX yet - please fix?] find out about the
  58 state of VMS. If it's bad, think again.
  59
  60 =item *
  61
  62 Rebuild META.yml:
  63
  64     $ rm META.yml
  65     $ make META.yml
  66
  67 and commit it if it's changed.
  68
  69 =item *
  70
  71 Check that the manifest is sorted and correct:
  72
  73     $ make distclean
  74     $ perl Porting/manisort
  75     $ perl Porting/manicheck
  76
  77 =item *
  78
  79 If this is a release candidate or final release, add an entry to
  80 F<pod/perlhist.pod> with the current date, e.g.
  81
  82           5.8.9-RC1     2008-Nov-10
  83
  84 Make sure the correct pumpking is listed, and if this is your first time,
  85 append your name to C<THE KEEPERS OF THE PUMPKIN>.
  86
  87 =item *
  88
  89 Build perl, then make sure it passes its own test suite, and installs.
  90
  91 =item *
  92
  93 Create a tarball. Use the C<-s> option to specify a suitable suffix for
  94 the tarball and directory name:
  95
  96     $ cd root/of/perl/tree
  97     $ git clean -xdf            #  make sure perl and git agree on files
  98
  99     $ perl Porting/makerel -s `git describe` # for a snapshot
 100     $ perl Porting/makerel -s RC1            # for a release candidate
 101     $ perl Porting/makerel                   # for a final release
 102
 103 This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
 104 the MANIFEST files into it, sets the correct permissions on them,
 105 adds DOS line endings to some, then tars it up as
 106 F<../perl-x.y.z-RC1.tar.gz>.
 107
 108 XXX if we go for extra tags and branches stuff, then add the extra details
 109 here
 110
 111 =item *
 112
 113 Copy the tarball to a web server somewhere you have access to.
 114
 115 =item *
 116
 117 Download the tarball to some other machine (for a release candidate, to two or
 118 more servers: IRC is good for this).
 119
 120 =item *
 121
 122 Check that C<./Configure -des && make all test> works in one place.
 123
 124 =item *
 125
 126 Check that C<./Configure ... && make all test_harness install> works.
 127
 128 =item *
 129
 130 Check that the output of C<perl -v> and C<perl -V> are as expected,
 131 especially as regards version numbers, patch and/or RC levels, and @INC
 132 paths. Note that the results may be different without a F<.git/> directory,
 133 which is why you should test from the tarball.
 134
 135 =item *
 136
 137 Bootstrap the CPAN client on the clean install.
 138
 139 =item *
 140
 141 Install CPANPLUS.
 142 XXX pick something new; this is now bundled
 143
 144 =item *
 145
 146 Bootstrap the CPANPLUS client.
 147
 148 =item *
 149
 150 Install an XS module.
 151
 152 =item *
 153
 154 If all is well, announce the snaphot to p5p. (For a release candidate,
 155 instead follow the further steps described later.)
 156
 157 =back
 158
 159 =head2  Actions prior to the first release candidate
 160
 161 A week or two before the first release candidate, there are some additional
 162 tasks you should perform (actually, some of these should be done regularly
 163 anyway, but they definitely need doing now):
 164
 165 =over 4
 166
 167 =item *
 168
 169 Check F<Maintainers.pl> for consistency; both these commands should
 170 produce no output:
 171
 172     perl Porting/Maintainers --checkmani
 173     perl Porting/Maintainers --checkmani lib/ ext/
 174
 175 =item *
 176
 177 Ensure that dual-life CPAN modules are synchronised with CPAN.  Basically,
 178 run the following:
 179
 180     ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
 181
 182 to see any inconsistencies between the core and CPAN versions of distros,
 183 then fix the core, or cajole CPAN authors as appropriate. See also the
 184 C<-d> and C<-v> options for more detail.  You'll probably want to use the
 185 C<-c cachedir> option to avoid repeated CPAN downloads.
 186
 187 To see which core distro versions differ from the current CPAN versions:
 188
 189     ./perl -Ilib Porting/core-cpan-diff -x -a
 190
 191 =item *
 192
 193 Ensure dual-life CPAN modules are stable, which comes down to:
 194
 195     for each module that fails its regression tests on $current
 196         did it fail identically on $previous?
 197         if yes, "SEP" (Somebody Else's Problem)
 198         else work out why it failed (a bisect is useful for this)
 199
 200     attempt to group failure causes
 201
 202     for each failure cause
 203         is that a regression?
 204         if yes, figure out how to fix it
 205             (more code? revert the code that broke it)
 206         else
 207             (presumably) it's relying on something un-or-under-documented
 208             should the existing behaviour stay?
 209                 yes - goto "regression"
 210                 no - note it in perldelta as a significant bugfix
 211                 (also, try to inform the module's author)
 212
 213 =item *
 214
 215 Similarly, monitor the smoking of core tests, and try to fix.
 216
 217 =item *
 218
 219 Run F<Porting/cmpVERSION.pl> to compare the current source tree with the
 220 previous version to check for for modules that have identical version
 221 numbers but different contents, e.g.:
 222
 223      $ cd ~/some-perl-root
 224      $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 .
 225
 226 then bump the version numbers of any non-dual-life modules that have
 227 changed since the previous release, but which still have the old version
 228 number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x),
 229 then compare against both.
 230
 231 Note that some of the files listed may be generated (e.g. copied from ext/
 232 to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm);
 233 make sure you edit the correct file!
 234
 235 Once all version numbers have been bumped, re-run the checks.
 236
 237 Then run again without the -x option, to check that dual-life modules are
 238 also sensible.
 239
 240
 241 =item *
 242
 243 Get perldelta in a mostly finished state.
 244 XXX expand
 245
 246 =item *
 247
 248 Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
 249
 250 There is a tool to semi-automate this process. It works in two stages.
 251 First, it generates a list of suggested changes, which you review and
 252 edit; then you feed this list back and it applies the edits. So, first
 253 scan the source dir looking for likely  candidates:
 254
 255     $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
 256
 257 This produces a file containing a list of suggested edits, eg:
 258
 259     NetWare/Makefile
 260
 261        89: -MODULE_DESC     = "Perl 5.10.0 for NetWare"
 262            +MODULE_DESC     = "Perl 5.10.1 for NetWare"
 263
 264 i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
 265 Review the file carefully, and delete any -/+ line pairs that you don't
 266 want changing. Remember that this tool is largely just grepping for '5.10.0'
 267 or whatever, so it will generate false positives. Be careful not change
 268 text like "this was fixed in 5.10.0"! Then run:
 269
 270     $ Porting/bump-perl-version -u < /tmp/scan
 271
 272 which will update all the files shown; then commit the changes.
 273
 274 Be particularly careful with F<INSTALL>, which contains a mixture of
 275 C<5.10.0>-type strings, some of which need bumping on every release, and
 276 some of which need to be left. Also note that this tool currently only
 277 performs a single change per line, so in particular, this line in
 278 README.vms needs special handling:
 279
 280     rename perl-5^.10^.1.dir perl-5_10_1.dir
 281
 282 =item *
 283
 284 Update the F<Changes> file to contain the git log command which would show
 285 all the changes in this release. You will need assume the existence of a
 286 not-yet created tag for the forthcoming release; e.g.
 287
 288     git log ... perl-5.10.0..perl5.12.0
 289
 290 Due to warts in the perforce-to-git migration, some branches require extra
 291 exclusions to avoid other branches being pulled in. Make sure you have the
 292 correct incantation: replace the not-yet-created tag with C<HEAD> and see
 293 if git log produces roughly the right number of commits across roughly the
 294 right time period.
 295
 296 =item *
 297
 298 Check some more build configurations, e.g.
 299
 300      -Duseshrplib -Dd_dosuid
 301      make suidperl
 302
 303 Check that setuid installs works (for < 5.11.0 only).
 304 XXX any other configs?
 305
 306 =item *
 307
 308 Make sure you have a PAUSE account suitable for uploading a perl release.
 309 If you don't have a PAUSE account, then request one:
 310
 311     https://pause.perl.org/pause/query?ACTION=request_id
 312
 313 Check that your account is allowed to upload perl distros: goto
 314 https://pause.perl.org/, login, then select 'upload file to CPAN'; there
 315 should be a "For pumpkings only: Send a CC" tickbox.  If not, ask Andreas
 316 to add your ID to the list of people allowed to upload something called
 317 perl.
 318
 319 =item *
 320
 321 Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if
 322 necessary, update the script to include new alias mappings.
 323
 324 XXX This script is currently broken (7/2009). It needs updating to work
 325 with git and a lack of Changes files.
 326
 327 =back
 328
 329 =head2  Building a release candidate
 330
 331 (At this point you should already have performed the actions described in
 332 L</"Actions prior to the first release candidate">.)
 333
 334 =over 4
 335
 336 =item *
 337
 338 Re-read the perldelta to try to find any embarrassing typos and thinkos;
 339 remove any C<TODO> or C<XXX> flags; and run through pod and spell
 340 checkers.   [XXX show how]
 341
 342 =item *
 343
 344 Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a
 345 final release, remove it.  [ XXX how now?? see 34813 for old way ]
 346
 347 =item *
 348
 349 Update C<Module::Corelist>.
 350
 351 Note that if this is a maint release, you should run the following actions
 352 from the maint directory, but edit the C<Corelist.pm> in I<blead> and
 353 subsequently cherry-pick it.
 354
 355 First, in order to update the C<%upstream> and C<%bug_tracker> hashes,
 356 the C<Porting/corelist.pl> script requires you to have a local CPAN
 357 mirror.  See http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN for
 358 more details, but basically:
 359
 360     $ mkdir ~/cpan-mirror
 361     $ rsync -av --delete ftp.funet.fi::CPAN ~/cpan-mirror/
 362
 363 (and re-run the rsync each time you need it to be up-to-date).
 364 [XXX this really needs fixing to not require a whole CPAN mirror]
 365
 366 If necessary, bump C<$VERSION> (there's no need to do this for
 367 every RC; in RC1, bump the version to a new clean number that will
 368 appear in the final release, and leave as-is for the later RCs and final).
 369
 370 Then do
 371
 372     $ cd ~/perl/root; make perl
 373     $ ./perl -Ilib Porting/corelist.pl ~/cpan-mirror/ > /tmp/corelist
 374
 375 This creates a file that looks something like
 376
 377     5.010001 => {
 378         'AnyDBM_File'           => '1.00',
 379         ...
 380     },
 381
 382     %upstream = (
 383         'App::Prove'            => undef,
 384         ...
 385     );
 386
 387     %bug_tracker = (
 388         'App::Prove'            => 'http://rt.cpan.org/...',
 389         ...
 390     );
 391
 392 Cut and paste these tables into F<lib/Module/CoreList.pm>: the module
 393 version list should be appended as the last entry in the C<%version> hash
 394 (or replaced, if we've already added it for an earlier release candidate),
 395 while the existing C<%upstream> and C<%bug_tracker> hashes should be
 396 replaced with the new versions.
 397
 398 Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
 399 entry, as that is likely to reflect the previous version number.
 400
 401 Then, add the current perl version to the C<CAVEATS> paragraph.
 402
 403 Add or update an entry to the C<%released> hash, including today's date
 404 (if this is just a release candidate, set the date to '????-??-??').
 405
 406
 407 =item *
 408
 409 Follow the instructions in the section L</"Building a snapshot">, then
 410 carry on with the extra steps that follow here.
 411
 412 =item *
 413
 414 Disarm the patchlevel.h change [ XXX expand ]
 415
 416 =item *
 417
 418 Wait for the smoke tests to catch up with the commit which this release is
 419 based on (or at least the last commit of any consequence).
 420
 421 Then check that the smoke tests pass (particularly on Win32). If not, go
 422 back and fix things.
 423
 424
 425 =item *
 426
 427 Once smoking is okay, upload it to PAUSE. This is the point of no return.
 428 You may wish to create a .bz2 version of the tarball and upload that too.
 429
 430 =item *
 431
 432 create a tag [XXX and branches and stuff ????], e.g.:
 433
 434     $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
 435     $ git push origin tag perl-5.10.1-RC1
 436
 437 =item *
 438
 439 Mail p5p to announce it, with a quote you prepared earlier.
 440
 441 =item *
 442
 443 Wait 24 hours or so, then post the announcement to use.perl.org.
 444 (if you don't have access rights to post news, ask someone like Rafael to
 445 do it for you.)
 446
 447 =back
 448
 449
 450 =head2  Making a final release
 451
 452 At this point you should have a working release candidate with few or no
 453 changes since.
 454
 455 It's essentially the same procedure as for making a release candidate, but
 456 with a whole bunch of extra post-release steps.
 457
 458 =over 4
 459
 460 =item *
 461
 462 Follow the same steps as for making a release candidate, then
 463
 464 =item *
 465
 466 Ask Jarkko to update http://www.cpan.org/src/README.html and
 467 Rafael to update http://dev.perl.org/perl5/
 468
 469 =item *
 470
 471 Create a new empty perlNNNdelta.pod file for the current release + 1;
 472 see F<Porting/how_to_write_a_perldelta.pod>.
 473 [ XXX Perhaps we should have an empty template file we can copy in. ]
 474
 475 In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
 476 entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
 477 following files:
 478
 479     MANIFEST
 480     pod/perl.pod
 481     win32/pod.mak
 482     vms/descrip_mms.template
 483
 484 (F<vms/descrip_mms.template> still needs a manual edit to bump the
 485 C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
 486
 487 and change perlNNNdelta references to the new version in these files
 488
 489     INSTALL
 490     win32/Makefile.mk
 491     win32/Makefile
 492     Makefile.SH
 493     README
 494
 495 Also, edit the previous delta file to change the C<NAME> from C<perldelta>
 496 to C<perlNNNdelta>.
 497
 498 These two lists of files probably aren't exhaustive; do a recursive grep
 499 on the previous filename to look for suitable candidates.
 500
 501 (see 16410843ea for an example).
 502
 503 =item *
 504
 505 If this was a major release, then
 506
 507 =over
 508
 509 =item *
 510
 511 bump the version, e.g. 5.12.0 to 5.13.0;
 512
 513 =item *
 514
 515 [ XXX probably lots more stuff to do, including perldelta,
 516 C<lib/feature.pm> ]
 517
 518 =item *
 519
 520 Create a new maint branch with an empty Porting/mergelog file
 521 [ XXX and lots of other stuff too, probably ]
 522
 523 =back
 524
 525 =item *
 526
 527 Copy the perlNNNdelta.pod for this release into the other branches, and
 528 remember to update these files on those branches too:
 529
 530     MANIFEST
 531     pod.lst
 532     pod/perl.pod
 533     vms/descrip_mms.template
 534     win32/pod.mak
 535
 536 (see fc5be80860 for an example).
 537
 538 =item *
 539
 540 Make sure any recent F<pod/perlhist.pod> entries are copied to
 541 F<perlhist.pod> on other branches; typically the RC* and final entries,
 542 e.g.
 543
 544           5.8.9-RC1     2008-Nov-10
 545           5.8.9-RC2     2008-Dec-06
 546           5.8.9         2008-Dec-14
 547
 548 =item *
 549
 550 Remind the current maintainer of C<Module::CoreList> to push a new release
 551 to CPAN.
 552
 553 =back
 554
 555 =head1 SOURCE
 556
 557 Based on
 558 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
 559 plus a whole bunch of other sources, including private correspondence.
 560
 561 =cut
 562