release_managers_guide: make into two logical sections:

those to be done in the week or two before a release,
and those to be done on the day

(cherry picked from commit 2e831dfd27333e967620fa1e890ab82ad077c64d)

1 files changed, 52 insertions, 27 deletions

diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 81f63a0b09..2411ef7c93 100644
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -139,7 +139,7 @@ in having one for a snapshot, but it's not required).
 =back
 
 
-=head2 Building a release
+=head2 Building a release - advance actions
 
 The work of building a release candidate for a numbered release of
 perl generally starts several weeks before the first release candidate.
@@ -236,23 +236,6 @@ also sensible.
 
 =item *
 
-Check that files managed by F<regen.pl> and friends are up to date. From
-within your working directory:
-
-
-    $ git status
-    $ make regen
-    $ make regen_perly
-    $ git status
-
-If any of the files managed by regen.pl have changed, then you should commit
-the updated versions:
-
-    $ git commit -m 'Updated files generated by regen tools for perl 5.x.y' <list of files>
-
-
-=item *
-
 I<You MAY SKIP this step for SNAPSHOT>
 
 Get perldelta in a mostly finished state.
@@ -265,7 +248,11 @@ edit the whole document.
 
 I<You MUST SKIP this step for SNAPSHOT>
 
-Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
+A week or two before the first release candidate, bump the perl version
+number (e.g. from 5.10.0 to 5.10.1), to allow sufficient time for testing
+and smoking with the target version built into the perl executable. For
+subsequent release candidates and the final release, it it not necessary
+to bump the version further.
 
 There is a tool to semi-automate this process. It works in two stages.
 First, it generates a list of suggested changes, which you review and
@@ -353,6 +340,21 @@ 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.
 
+=back
+
+=head2 Building a release - on the day
+
+This section describes the actions required to make a release (or snapshot
+etc) that are performed on the actual day.
+
+=over 4
+
+=item *
+
+Review all the items in the previous section,
+L<"Building a release - advance actions"> to ensure they are all done and
+up-to-date.
+
 =item *
 
 Configure and build perl so that you have a Makefile and porting tools:
@@ -360,6 +362,25 @@ 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:
+
+    $ git status
+    $ make regen
+    $ make regen_perly
+    $ git status
+
+If any of the files managed by regen.pl have changed, then you should commit
+the updated versions:
+
+    $ git commit -m 'Updated files generated by regen tools for perl 5.x.y' <list of files>
+
+
 =item *
 
 Rebuild META.yml:
@@ -390,7 +411,7 @@ Commit MANIFEST if it has changed:
 
 I<You MUST SKIP this step for SNAPSHOT>
 
-A dd an entry to F<pod/perlhist.pod> with the current date:
+Add an entry to F<pod/perlhist.pod> with the current date:
 
           5.8.9-RC1     2008-Nov-10
 
@@ -486,11 +507,6 @@ Finally, commit the new version of Module::CoreList:
     $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \
      lib/Module/Corelist.pm
 
-
-=item *
-
-Disarm the patchlevel.h change [ XXX expand ]
-
 =item *
 
 Build perl, then make sure it passes its own test suite, and installs:
@@ -610,13 +626,22 @@ You may wish to create a .bz2 version of the tarball and upload that too.
 
 I<You MUST SKIP this step for SNAPSHOT>
 
-Create a tag for the exact git revsion you built the release from:
+Create a tag for the exact git revision you built the release from.
+C<commit> below is the commit corresponding to the tarball. It can be
+omitted if there have been no further commits since the tarball was
+created.
 
-    $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
+    $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' <commit>
     $ git push origin tag perl-5.10.1-RC1
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
+Disarm the patchlevel.h change [ XXX expand ]
+
+=item *
+
 Mail p5p to announce your new release, with a quote you prepared earlier.
 
 =item *