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 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 is 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 No
 393
 394 Cut and paste these tables into F<lib/Module/CoreList.pm>: the module
 395 version list should be appended as the last entry in the C<%version> hash
 396 (or replaced, if we've already added it for an earlier release candidate),
 397 while the existing C<%upstream> and C<%bug_tracker> hashes should be
 398 replaced with the new versions.
 399
 400 Edit the version number in the new C<<'Module::CoreList' => 'X.YZ'>>
 401 entry, as that is likely to reflect the previous version number.
 402
 403 Then, add the current perl version to the C<CAVEATS> paragraph.
 404
 405 Add or update an entry to the C<%released> hash, including today's date
 406 (if this is just a release candidate, set the date to '????-??-??').
 407
 408
 409 =item *
 410
 411 Follow the instructions in the section L</"Building a snapshot">, then
 412 carry on with the extra steps that follow here.
 413
 414 =item *
 415
 416 Wait for the smoke tests to catch up with the commit which this release is
 417 based on (or at least the last commit of any consequence).
 418
 419 Then check that the smoke tests pass (particularly on Win32). If not, go
 420 back and fix things.
 421
 422
 423 =item *
 424
 425 Once smoking is okay, upload it to PAUSE. This is the point of no return.
 426
 427 XXX check whether need to upload .bz2,.meta, .readme too?
 428
 429 =item *
 430
 431 create a tag [XXX and branches and stuff ????], e.g.:
 432
 433     $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
 434     $ git push origin tag perl-5.10.1-RC1
 435
 436 =item *
 437
 438 Mail p5p to announce it, with a quote you prepared earlier.
 439
 440 =item *
 441
 442 Wait 24 hours or so, then post the announcement to use.perl.org.
 443
 444 =back
 445
 446
 447 =head2  Making a final release
 448
 449 At this point you should have a working release candidate with few or no
 450 changes since.
 451
 452 It's essentially the same procedure as for making a release candidate, but
 453 with a whole bunch of extra post-release steps.
 454
 455 =over 4
 456
 457 =item *
 458
 459 Follow the same steps as for making a release candidate, then
 460
 461 =item *
 462
 463 Ask Jarkko to update http://www.cpan.org/src/README.html and
 464 Rafael to update http://dev.perl.org/perl5/
 465
 466
 467 =item *
 468
 469 [ XXX disarm any patchlevel.h stuff ??? ]
 470
 471 =item *
 472
 473 Create a new empty perlNNNdelta.pod file for the current release + 1;
 474 see F<Porting/how_to_write_a_perldelta.pod>.
 475 [ XXX Perhaps we should have an empty template file we can copy in. ]
 476
 477 In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
 478 entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
 479 following files:
 480
 481     MANIFEST
 482     pod/perl.pod
 483     win32/pod.mak
 484     vms/descrip_mms.template
 485
 486 (F<vms/descrip_mms.template> still needs a manual edit to bump the
 487 C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
 488
 489 and change perlNNNdelta references to the new version in these files
 490
 491     INSTALL
 492     win32/Makefile.mk
 493     win32/Makefile
 494     Makefile.SH
 495     README
 496
 497 Also, edit the previous delta file to change the C<NAME> from C<perldelta>
 498 to C<perlNNNdelta>.
 499
 500 These two lists of files probably aren't exhaustive; do a recursive grep
 501 on the previous filename to look for suitable candidates.
 502
 503 (see 16410843ea for an example).
 504
 505 =item *
 506
 507 If this was  major release, bump the version, e.g. 5.12.0 to 5.13.0
 508 [ XXX probably more complex stuff to do, including perldelta,
 509 C<lib/feature.pm> ]
 510
 511 =item *
 512
 513 Copy the perlNNNdelta.pod for this release into the other branches, and
 514 remember to update these files on those branches too:
 515
 516     MANIFEST
 517     pod.lst
 518     pod/perl.pod
 519     vms/descrip_mms.template
 520     win32/pod.mak
 521
 522 (see fc5be80860 for an example).
 523
 524 =item *
 525
 526 Make sure any recent F<pod/perlhist.pod> entries are copied to
 527 F<perlhist.pod> on other branches; typically the RC* and final entries,
 528 e.g.
 529
 530           5.8.9-RC1     2008-Nov-10
 531           5.8.9-RC2     2008-Dec-06
 532           5.8.9         2008-Dec-14
 533
 534 =item *
 535
 536 Remind the current maintainer of C<Module::CoreList> to push a new release
 537 to CPAN.
 538
 539 =back
 540
 541 =head1 SOURCE
 542
 543 Based on
 544 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
 545 plus a whole bunch of other sources, including private correspondence.
 546
 547 =cut
 548