Linearized the release-manager's guide to make it less of a choose-your-own-adventure...
authorJesse Vincent <jesse@bestpractical.com>
Fri, 31 Jul 2009 15:28:36 +0000 (11:28 -0400)
committerDavid Mitchell <davem@iabyn.com>
Mon, 3 Aug 2009 22:01:19 +0000 (23:01 +0100)
(cherry picked from commit 8c35d285401fe5adc3a2123303047b3c9caf49e7)

Porting/release_managers_guide.pod

index 71c607f..137579e 100644 (file)
@@ -1,4 +1,3 @@
-
 =head1 NAME
 
 release_managers_guide - Releasing a new version of perl 5.x
@@ -13,13 +12,14 @@ tools may need updating. DAPM
 
 This document describes the series of tasks required - some automatic, some
 manual - to produce a perl release of some description, be that a snaphot,
-release candidate, or final release.
+release candidate, or final, numbered release of maint or blead.
 
-The release process is primarily executed by the current pumpking.
+The release process has traditionally been executed by the current
+pumpking.
 
-This document both helps as a check-list for the pumpking and is
-a base for ideas on how the various tasks could be automated or 
-distributed.
+This document both helps as a check-list for the release engineer 
+and is a base for ideas on how the various tasks could be automated 
+or distributed.
 
 The outline of a typical release cycle is as follows:
 
@@ -48,6 +48,42 @@ The outline of a typical release cycle is as follows:
 
 =head1 DETAILS
 
+Some of the tasks described below apply to all four types of 
+release of Perl. (snapshot, RC, final release of maint, final 
+release of blead). Some of these tasks apply only to a subset
+of these release types.  If a step does not apply to a given 
+type of release, you will see a notation to that effect at
+the beginning of the step.
+
+=head2 Release types
+
+=over 4
+
+=item Snapshot
+
+A snapshot is intended to encourage in-depth testing from time-to-time,
+for example after a key point in the stabilisation of a branch. It
+requires fewer steps than a full release, and the version number of perl in
+the tarball will usually be the same as that of the previous release.
+
+=item Release Candidate (RC)
+
+XXX Describe me
+
+=item Stable/Maint release
+
+At this point you should have a working release candidate with few or no
+changes since.
+
+It's essentially the same procedure as for making a release candidate, but
+with a whole bunch of extra post-release steps.
+
+=item Blead release
+
+It's essentially the same procedure as for making a release candidate, but
+with a whole bunch of extra post-release steps.
+
+=back
 
 =head2 Prerequisites
 
@@ -56,7 +92,9 @@ hoops you need to jump through:
 
 =over 4
 
-=item *
+=item PAUSE account
+
+I<SKIP this step for SNAPSHOT>
 
 Make sure you have a PAUSE account suitable for uploading a perl release.
 If you don't have a PAUSE account, then request one:
@@ -71,7 +109,13 @@ called perl.  You can find Andreas' email address at:
     
     https://pause.perl.org/pause/query?ACTION=pause_04imprint
 
-=item *
+=item CPAN mirror
+
+Some release engineering steps require a full mirror of the CPAN.
+Work to fall back to using a remote mirror via HTTP is incomplete
+but ongoing. (No, a minicpan mirror is not sufficient)
+
+=item git checkout and commit bit
 
 You will need a working C<git> installation, checkout of the perl
 git repository and perl commit bit.  For information about working
@@ -82,172 +126,32 @@ release.  Have a chat with whichever evil perl porter tried to talk
 you into the idea in the first place to figure out the best way to
 resolve the issue.
 
-=back
-
-
-=head2 Building a snapshot
-
-A snapshot is intended to encourage in-depth testing from time-to-time,
-for example after a key point in the stabilisation of a branch. It
-requires fewer steps than a full release, and the version number of perl in
-the tarball will usually be the same as that of the previous release.
-
-=over 4
-
-=item *
-
-As there are no regular smokes [ XXX yet - please fix?] find out about the
-state of the current branch on VMS. If the branch you're releasing on
-is failing tests on VMS, you may not want to do a release.
-
-=item *
-
-Configure and build perl so that you have a Makefile and porting tools:
-
-    $ ./Configure -Dusedevel -des
-    $ make
-
-=item *
-
-Rebuild META.yml:
-
-    $ rm META.yml
-    $ make META.yml
-
-Commit META.yml if it has changed:
-
-    $ git commit -m 'Updating META.yml in preparation for release of 5.x.y' META.yml
-
-=item *
 
-Check that the manifest is sorted and correct:
+=item Quotation for release announcement epigraph
 
-    $ make manisort
-    $ make distclean 
-    $ perl Porting/manicheck
+I<SKIP this step for SNAPSHOT and RC>
 
+For a numbered blead or maint release of perl, you will need a quotation 
+to use as an epigraph to your release announcement.  (There's no harm
+in having one for a snapshot, but it's not required).
 
-Commit MANIFEST if it has changed:
-
-    $ git commit -m 'Updating MANIFEST in preparation for release of 5.x.y' MANIFEST
-
-
-
-=item *
-
-If this is a release candidate or final release, add an entry to
-F<pod/perlhist.pod> with the current date, e.g.
-
-          5.8.9-RC1     2008-Nov-10
-
-Make sure the correct pumpking is listed, and if this is your first time,
-append your name to C<THE KEEPERS OF THE PUMPKIN>.
-
-=item *
-
-Build perl, then make sure it passes its own test suite, and installs:
-
-    $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
-    $ make test install
-
-=item *
-
-Create a tarball. Use the C<-s> option to specify a suitable suffix for
-the tarball and directory name:
-
-    $ cd root/of/perl/tree
-    $ make distclean
-    $ git clean -xdf           #  make sure perl and git agree on files
-
-    $ perl Porting/makerel -b -s `git describe` # for a snapshot
-    $ perl Porting/makerel -b -s RC1            # for a release candidate
-    $ perl Porting/makerel -b                   # for a final release
-
-This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
-the MANIFEST files into it, sets the correct permissions on them,
-adds DOS line endings to some, then tars it up as
-F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
-
-XXX if we go for extra tags and branches stuff, then add the extra details
-here
-
-=item *
-
-Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
-have access to.
-
-=item *
-
-Download the tarball to some other machine. For a release candidate, 
-you really want to test your tarball on two or more different platforms
-and architectures. The #p5p IRC channel on irc.perl.org is a good place
-to find willing victims.
-
-=item *
-
-Check that basic configuration and tests work on each test machine:
-
-    $ ./Configure -des && make all test
-
-=item *
-
-Check that the test harness and install work on each test machine:
-
-    $ ./Configure -des -Dprefix=/install/path && make all test_harness install
-
-=item *
-
-Check that the output of C<perl -v> and C<perl -V> are as expected,
-especially as regards version numbers, patch and/or RC levels, and @INC
-paths. 
-
-Note that the results may be different without a F<.git/> directory,
-which is why you should test from the tarball.
-
-=item *
-
-Bootstrap the CPAN client on the clean install:
-
-    $ ./bin/perl -MCPAN -e'shell' 
-
-=item *
-
-Install Inline.pm 
-
-    $ ./bin/perl -MCPAN -e'install Inline'
-
-Check that your perl can run this:
-
-    $ ./bin/perl -lwe 'use Inline C => "int answer() { return 42;} "; print answer'
-
-=item *
-
-Bootstrap the CPANPLUS client on the clean install:
-
-    $ ./bin/cpanp
-
-
-=item *
-
-Install an XS module.
-
-=item *
-
-If all is well, announce the snapshot to p5p. (For a release candidate,
-instead follow the further steps described later.)
 
 =back
 
-=head2  Actions prior to the first release candidate
 
-A week or two before the first release candidate, there are some additional
-tasks you should perform (actually, some of these should be done regularly
-anyway, but they definitely need doing now):
+=head2 Building a release
+
+The work of building a release candidate for a numbered release of
+perl generally starts several weeks before the first release candidate.
+Some of these should be done regularly, but all I<must> be done in the 
+runup to a release.
 
 =over 4
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Check F<Maintainers.pl> for consistency; both these commands should
 produce no output:
 
@@ -256,6 +160,8 @@ produce no output:
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Ensure that dual-life CPAN modules are synchronised with CPAN.  Basically,
 run the following:
 
@@ -278,6 +184,8 @@ have some extra changes.
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Ensure dual-life CPAN modules are stable, which comes down to:
 
     for each module that fails its regression tests on $current
@@ -300,15 +208,21 @@ Ensure dual-life CPAN modules are stable, which comes down to:
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Similarly, monitor the smoking of core tests, and try to fix.
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Similarly, monitor the smoking of perl for compiler warnings, and try to
 fix.
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Run F<Porting/cmpVERSION.pl> to compare the current source tree with the
 previous version to check for for modules that have identical version
 numbers but different contents, e.g.:
@@ -349,6 +263,8 @@ the updated versions:
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Get perldelta in a mostly finished state.
 
 Peruse  F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
@@ -357,6 +273,8 @@ edit the whole document.
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
 
 There is a tool to semi-automate this process. It works in two stages.
@@ -394,11 +312,15 @@ README.vms needs special handling:
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Review and update INSTALL to account for the change in version number;
 in particular, the "Coexistence with earlier versions of perl 5" section.
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Update the F<Changes> file to contain the git log command which would show
 all the changes in this release. You will need assume the existence of a
 not-yet created tag for the forthcoming release; e.g.
@@ -425,25 +347,172 @@ XXX any other configs?
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if
 necessary, update the script to include new alias mappings.
 
 XXX This script is currently broken (7/2009). It needs updating to work
 with git and a lack of Changes files.
 
-=back
 
-=head2  Building a release candidate
+=item *
 
-(At this point you should already have performed the actions described in
-L</"Actions prior to the first release candidate">.) You should review
-that section to ensure that everything there has done, and to see whether
-any of those actions (such as consistency checks) need to be repeated.
+I<You MAY SKIP this step for SNAPSHOT>
 
-=over 4
+As there are no regular smokes [ XXX yet - please fix?] find out about the
+state of the current branch on VMS. If the branch you're releasing on
+is failing tests on VMS, you may not want to do a release.
+
+=item *
+
+Configure and build perl so that you have a Makefile and porting tools:
+
+    $ ./Configure -Dusedevel -des
+    $ make
+
+=item *
+
+Rebuild META.yml:
+
+    $ rm META.yml
+    $ make META.yml
+
+Commit META.yml if it has changed:
+
+    $ git commit -m 'Updating META.yml in preparation for release of 5.x.y' META.yml
+
+=item *
+
+Check that the manifest is sorted and correct:
+
+    $ make manisort
+    $ make distclean 
+    $ perl Porting/manicheck
+
+
+Commit MANIFEST if it has changed:
+
+    $ git commit -m 'Updating MANIFEST in preparation for release of 5.x.y' MANIFEST
+
+
+
+=item *
+
+I<You MUST SKIP this step for SNAPSHOT>
+
+A dd an entry to F<pod/perlhist.pod> with the current date:
+
+          5.8.9-RC1     2008-Nov-10
+
+Make sure the correct pumpking is listed, and if this is the first release
+under the stewardship of a new pumpking, make sure that his or her name
+is listed in the section entitled C<THE KEEPERS OF THE PUMPKIN>.
+
+Be sure to commit your changes:
+
+    $ git commit -m 'Updating perlhist in preparation for release of 5.x.y pod/perlhist.pod
+
+
+=item *
+
+Build perl, then make sure it passes its own test suite, and installs:
+
+    $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
+    $ make test install
+
+=item *
+
+Create a tarball. Use the C<-s> option to specify a suitable suffix for
+the tarball and directory name:
+
+    $ cd root/of/perl/tree
+    $ make distclean
+    $ git clean -xdf           #  make sure perl and git agree on files
+
+    $ perl Porting/makerel -b -s `git describe` # for a snapshot
+    $ perl Porting/makerel -b -s RC1            # for a release candidate
+    $ perl Porting/makerel -b                   # for a final release
+
+This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
+the MANIFEST files into it, sets the correct permissions on them,
+adds DOS line endings to some, then tars it up as
+F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
+
+XXX if we go for extra tags and branches stuff, then add the extra details
+here
+
+=item *
+
+Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
+have access to.
+
+=item *
+
+Download the tarball to some other machine. For a release candidate, 
+you really want to test your tarball on two or more different platforms
+and architectures. The #p5p IRC channel on irc.perl.org is a good place
+to find willing victims.
+
+=item *
+
+Check that basic configuration and tests work on each test machine:
+
+    $ ./Configure -des && make all test
 
 =item *
 
+Check that the test harness and install work on each test machine:
+
+    $ ./Configure -des -Dprefix=/install/path && make all test_harness install
+
+=item *
+
+Check that the output of C<perl -v> and C<perl -V> are as expected,
+especially as regards version numbers, patch and/or RC levels, and @INC
+paths. 
+
+Note that the results may be different without a F<.git/> directory,
+which is why you should test from the tarball.
+
+=item *
+
+Bootstrap the CPAN client on the clean install:
+
+    $ ./bin/perl -MCPAN -e'shell' 
+
+=item *
+
+Install Inline.pm 
+
+    $ ./bin/perl -MCPAN -e'install Inline'
+
+Check that your perl can run this:
+
+    $ ./bin/perl -lwe 'use Inline C => "int answer() { return 42;} "; print answer'
+
+=item *
+
+Bootstrap the CPANPLUS client on the clean install:
+
+    $ ./bin/cpanp
+
+
+=item *
+
+Install an XS module.
+
+=item *
+
+If all is well, announce the snapshot to p5p. (For a release candidate,
+instead follow the further steps described later.)
+
+
+=item *
+
+
+I<You MAY SKIP this step for SNAPSHOT>
+
 Re-read the perldelta to try to find any embarrassing typos and thinkos;
 remove any C<TODO> or C<XXX> flags; and run through pod and spell
 checkers, e.g.
@@ -453,11 +522,15 @@ checkers, e.g.
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a
 final release, remove it.  [ XXX how now?? see 34813 for old way ]
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Update C<Module::Corelist>.
 
 Note that if this is a maint release, you should run the following actions
@@ -497,11 +570,9 @@ appear in the final release, and leave as-is for the later RCs and final).
 Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
 entry, as that is likely to reflect the previous version number.
 
+If this is a final release (rather than a release candidate):
 
-
-
-Add or update an entry to the C<%released> hash, including today's date
-(if this is just a release candidate, set the date to '????-??-??').
+    Update this version's entry in the C<%released> hash with today's date.
 
 Finally, commit the new version of Module::CoreList:
 
@@ -509,17 +580,14 @@ Finally, commit the new version of Module::CoreList:
      lib/Module/Corelist.pm
 
 
-=item *
-
-Follow the instructions in the section L</"Building a snapshot">, then
-carry on with the extra steps that follow here.
-
 =item *
 
 Disarm the patchlevel.h change [ XXX expand ]
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Wait for the smoke tests to catch up with the commit which this release is
 based on (or at least the last commit of any consequence).
 
@@ -529,6 +597,8 @@ back and fix things.
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Once smoking is okay, upload it to PAUSE. This is the point of no return.
 If anything goes wrong after this point, you will need to re-prepare
 a new release with a new minor version or RC number.
@@ -537,6 +607,8 @@ You may wish to create a .bz2 version of the tarball and upload that too.
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Create a tag for the exact git revsion you built the release from:
 
     $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
@@ -548,34 +620,24 @@ Mail p5p to announce your new release, with a quote you prepared earlier.
 
 =item *
 
+I<You MAY SKIP this step for SNAPSHOT>
+
 Wait 24 hours or so, then post the announcement to use.perl.org.
 (if you don't have access rights to post news, ask someone like Rafael to
 do it for you.)
 
-=back
-
-
-=head2  Making a final release
-
-At this point you should have a working release candidate with few or no
-changes since.
-
-It's essentially the same procedure as for making a release candidate, but
-with a whole bunch of extra post-release steps.
-
-=over 4
-
 =item *
 
-Follow the same steps as for making a release candidate, then
-
-=item *
+I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
 
 Ask Jarkko to update http://www.cpan.org/src/README.html and
 Rafael to update http://dev.perl.org/perl5/
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT, RC>
+
+
 Create a new empty perlNNNdelta.pod file for the current release + 1;
 see F<Porting/how_to_write_a_perldelta.pod>.
 [ XXX Perhaps we should have an empty template file we can copy in. ]
@@ -610,34 +672,31 @@ on the previous filename to look for suitable candidates.
 
 =item *
 
-If this was a maintenance release, then edit F<Porting/mergelog> to change
-all the C<d> (deferred) flags to C<.> (needs review).
-
+I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
 
-=item *
-
-If this was a major release, then
+If this was a maint release, then edit F<Porting/mergelog> to change
+all the C<d> (deferred) flags to C<.> (needs review).
 
-=over
+XXX - we should be able to use git to automate much of the role
+previously filled by the mergelog.
 
 =item *
 
-bump the version, e.g. 5.12.0 to 5.13.0;
+I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
 
-=item * 
+If this was a major release (5.x.0), then create a new maint branch 
+based on the commit tagged as the current release and bump the version 
+in the blead branch in git, e.g. 5.12.0 to 5.13.0.
 
 [ XXX probably lots more stuff to do, including perldelta,
 C<lib/feature.pm> ]
 
-=item *
-
-Create a new maint branch with an empty Porting/mergelog file
-[ XXX and lots of other stuff too, probably ]
-
-=back
+XXX need a git recipe
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
+
 Copy the perlNNNdelta.pod for this release into the other branches, and
 remember to update these files on those branches too:
 
@@ -651,6 +710,8 @@ remember to update these files on those branches too:
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
 Make sure any recent F<pod/perlhist.pod> entries are copied to
 F<perlhist.pod> on other branches; typically the RC* and final entries,
 e.g.
@@ -661,9 +722,18 @@ e.g.
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT, RC>
+
 Remind the current maintainer of C<Module::CoreList> to push a new release
 to CPAN.
 
+=item *
+
+I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some much-needed
+rest and relaxation>. 
+
+Thanks for releasing perl!
+
 =back
 
 =head1 SOURCE