release_managers_guide: tweak ordering of 'on-the-day' stuff
authorDavid Mitchell <davem@iabyn.com>
Thu, 6 Aug 2009 00:01:07 +0000 (01:01 +0100)
committerDavid Mitchell <davem@iabyn.com>
Thu, 6 Aug 2009 00:18:15 +0000 (01:18 +0100)
and lots of little fixes therein.

(cherry picked from commit a0db33fef579d4bbe3f26e2850101521e606c9db)

Porting/release_managers_guide.pod

index 17315dd..4d3a592 100644 (file)
@@ -357,89 +357,66 @@ up-to-date.
 
 =item *
 
-Configure and build perl so that you have a Makefile and porting tools:
-
-    $ ./Configure -Dusedevel -des
-    $ make
-
-XXX probably want some re-ordering here: we build a perl, and very soon
-afterwards do a distclean
-
-=item *
-
-Check that files managed by F<regen.pl> and friends are up to date. From
-within your working directory:
+I<You MAY SKIP this step for SNAPSHOT>
 
-    $ git status
-    $ make regen
-    $ make regen_perly
-    $ git status
+Re-read the perldelta to try to find any embarrassing typos and thinkos;
+remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
+with any serious issues for which fixes are not going to happen now; and
+run through pod and spell checkers, e.g.
 
-If any of the files managed by regen.pl have changed, then you should commit
-the updated versions:
+    podchecker -warnings -warnings pod/perl5101delta.pod
+    spell pod/perl5101delta.pod
 
-    $ git commit -m 'Updated files generated by regen tools for perl 5.x.y' <list of files>
+Also, you may want to generate and view an HTML version of it to check
+formatting, e.g.
 
+    perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html
 
 =item *
 
-Rebuild META.yml:
+Make sure you have a gitwise-clean perl directory (no modified files,
+unpushed commits etc):
 
-    $ 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
+    $ git status
 
 =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
-
+If not already built, Configure and build perl so that you have a Makefile
+and porting tools:
 
+    $ ./Configure -Dusedevel -des
+    $ make
 
 =item *
 
-I<You MUST SKIP this step for SNAPSHOT>
-
-Add 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>.
+Check that files managed by F<regen.pl> and friends are up to date. From
+within your working directory:
 
-Be sure to commit your changes:
+    $ git status
+    $ make regen
+    $ make regen_perly
+    $ git status
 
-    $ git commit -m 'Updating perlhist in preparation for release of 5.x.y' pod/perlhist.pod
+If any of the files managed by F<regen.pl> have changed, then you should
+re-make perl to check that it's okay, then commit the updated versions:
 
+    $ git commit -a -m 'make regn; make regn_perly'
 
 =item *
 
-I<You MAY SKIP this step for SNAPSHOT>
+Rebuild META.yml:
 
-Re-read the perldelta to try to find any embarrassing typos and thinkos;
-remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
-with any serious issues for which fixes are not going to happen now; and
-run through pod and spell checkers, e.g.
+    $ rm META.yml
+    $ make META.yml
+    $ git diff
 
-    podchecker -warnings -warnings pod/perl5101delta.pod
-    spell pod/perl5101delta.pod
+XXX it would be nice to make Porting/makemeta use regen_lib.pl
+to get the same 'update the file if its changed' functionality
+we get with 'make regen' etc.
 
-Also, you may want to generate and view an HTML version of it to check
-formatting, e.g.
+Commit META.yml if it has changed:
 
-    perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html
+    $ git commit -m 'Update META.yml' META.yml
 
 =item *
 
@@ -451,33 +428,38 @@ Note that if this is a maint release, you should run the following actions
 from the maint directory, but commit the C<Corelist.pm> changes in
 I<blead> and subsequently cherry-pick it.
 
-corelist.pl uses ftp.funet.fi to verify information about dual-lifed
+F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
 modules on CPAN. It can use a full, local CPAN mirror or fall back
 to C<wget> or C<curl> to fetch only package metadata remotely.
 
 (If you'd prefer to have a full CPAN mirror, see 
 http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
 
+Then change to your perl checkout, and if necessary,
 
-Then change to your perl checkout.
+    $ make perl
 
-If you have a local CPAN mirror, run:
+Thenn, If you have a local CPAN mirror, run:
 
-    $ make perl
     $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
 
 Otherwise, run:
 
-    $ make perl
     $ ./perl -Ilib Porting/corelist.pl cpan
 
 This will chug for a while. Assuming all goes well, it will
-update lib/Module/CoreList.pm. 
+update F<lib/Module/CoreList.pm>.
 
 Check that file over carefully:
 
     $ git diff lib/Module/CoreList.pm
 
+In particular, if this not the first update for this version, make sure
+that there isn't a duplicated entry (e.g. '5.010001' entries for both RC1
+and RC2).
+
+XXX the edit-in-place functionality of Porting/corelist.pl should
+be fixed to allow for this
 
 If necessary, bump C<$VERSION> (there's no need to do this for
 every RC; in RC1, bump the version to a new clean number that will
@@ -486,7 +468,7 @@ 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):
+In addition, if this is a final release (rather than a release candidate):
 
 =over 4 
 
@@ -501,16 +483,41 @@ Make sure that the script has correctly updated the C<CAVEATS> section
 =back
 
 Finally, commit the new version of Module::CoreList:
+(unless this is for maint; in which case commit it blead first, then
+cherry-pick it back).
 
     $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \
-     lib/Module/Corelist.pm
+     lib/Module/CoreList.pm
+
 
 =item *
 
-Build perl, then make sure it passes its own test suite, and installs:
+Check that the manifest is sorted and correct:
 
-    $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
-    $ make test install
+    $ make manisort
+    $ make distclean
+    $ perl Porting/manicheck
+
+Commit MANIFEST if it has changed:
+
+    $ git commit -m 'Update MANIFEST' MANIFEST
+
+=item *
+
+I<You MUST SKIP this step for SNAPSHOT>
+
+Add an entry to F<pod/perlhist.pod> with the current date, e.g.:
+
+    David    5.10.1-RC1    2009-Aug-06
+
+Make sure that the correct pumpking is listed in the left-hand column, 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 'add new release to perlhist' pod/perlhist.pod
 
 =item *
 
@@ -530,6 +537,27 @@ Be sure to commit your change:
 
 =item *
 
+Build perl, then make sure it passes its own test suite, and installs:
+
+    $ git clean -xdf
+    $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
+    $ make test 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.
+
+=item *
+
+Push all your recent commits:
+
+    $ git push origin ....
+
+
+=item *
+
 Create a tarball. Use the C<-s> option to specify a suitable suffix for
 the tarball and directory name: