From: Jesse Vincent Date: Fri, 31 Jul 2009 15:28:36 +0000 (-0400) Subject: Linearized the release-manager's guide to make it less of a choose-your-own-adventure... X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=8c35d285401fe5adc3a2123303047b3c9caf49e7;p=p5sagit%2Fp5-mst-13.2.git Linearized the release-manager's guide to make it less of a choose-your-own-adventure novel --- diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod index 71c607f..137579e 100644 --- a/Porting/release_managers_guide.pod +++ b/Porting/release_managers_guide.pod @@ -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 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 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 +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 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. - -=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 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 and C 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 be done in the +runup to a release. =over 4 =item * +I + Check F for consistency; both these commands should produce no output: @@ -256,6 +160,8 @@ produce no output: =item * +I + Ensure that dual-life CPAN modules are synchronised with CPAN. Basically, run the following: @@ -278,6 +184,8 @@ have some extra changes. =item * +I + 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 + Similarly, monitor the smoking of core tests, and try to fix. =item * +I + Similarly, monitor the smoking of perl for compiler warnings, and try to fix. =item * +I + Run F 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 + Get perldelta in a mostly finished state. Peruse F, and try to make sure that @@ -357,6 +273,8 @@ edit the whole document. =item * +I + 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 + 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 + Update the F 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 + Update F, using the C 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.) 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 -=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 + +A dd an entry to F 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. + +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 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 and C 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 + Re-read the perldelta to try to find any embarrassing typos and thinkos; remove any C or C flags; and run through pod and spell checkers, e.g. @@ -453,11 +522,15 @@ checkers, e.g. =item * +I + 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 + Update C. 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: @@ -511,15 +582,12 @@ Finally, commit the new version of Module::CoreList: =item * -Follow the instructions in the section L, then -carry on with the extra steps that follow here. - -=item * - Disarm the patchlevel.h change [ XXX expand ] =item * +I + 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 + 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 + 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 + 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 Ask Jarkko to update http://www.cpan.org/src/README.html and Rafael to update http://dev.perl.org/perl5/ =item * +I + + Create a new empty perlNNNdelta.pod file for the current release + 1; see F. [ 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 to change -all the C (deferred) flags to C<.> (needs review). - +I -=item * - -If this was a major release, then +If this was a maint release, then edit F to change +all the C (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 -=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 ] -=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 + 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 + Make sure any recent F entries are copied to F on other branches; typically the RC* and final entries, e.g. @@ -661,9 +722,18 @@ e.g. =item * +I + Remind the current maintainer of C to push a new release to CPAN. +=item * + +I. + +Thanks for releasing perl! + =back =head1 SOURCE