release_managers_guide: feedback from 5.15.0 bump

The version bump from 5.14.0 to 5.15.0 didn't go at all smoothly.
Update release_managers_guide based on that experience.

Basically there were a couple of catch-22 situations with auto-generated
files; namely uconfig.h and the pod/perl5150delta.pod link.

Also, I've split the 'bump bleed to 5.15' and 'make maint-5.14 branch'
instructions into two separate sections.

diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index cff0d23..c1754a9 100644 (file)
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -296,10 +296,14 @@ to an earlier release. When releasing a stable perl version, the C<PERL_API_*>
 constants C<MUST NOT> be changed as we aim to guarantee binary compatibility
 in maint branches.
 
+After editing, regenerate uconfig.h (this must be run on a system with a
+/bin/sh available):
 
+    $ perl regen/uconfig_h.pl
 
 Test your changes:
 
+    $ git clean -xdf   # careful if you don't have local files to keep!
     $ ./Configure -des -Dusedevel
     $ make
     $ make test
@@ -887,37 +891,44 @@ I<You MUST SKIP this step for RC>
 
 Create a new perldelta.
 
-First, update the F<.gitignore> file in the F<pod/> folder to ignore the next
-release's generated F<pod/perlNNNdelta.pod> file rather than this releases's
+B<Note>: currently, the buildtoc below must be run in a I<built> perl source
+directory, as at least one of the pod files it expects to find is
+autogenerated: perluniprops.pod. But you can't build perl if you've added
+the new perldelta file and not updated toc. So, make sure you have a built
+perl (with a pod/perluniprops.pod file) now, I<>before> continuing.
+
+First, update the F<pod/.gitignore> file  to ignore the next
+release's generated F<pod/perlNNNdelta.pod> file rather than this release's
 one which we are about to set in stone (where NNN is the perl version number
 without the dots. i.e. 5135 for 5.13.5).
 
-Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>.
-
-Now edit the moved delta file to change the C<NAME> from C<perldelta> to
-C<perlNNNdelta>.
-
-Then create a new empty perldelta.pod file for the new release; see
-F<Porting/how_to_write_a_perldelta.pod>.
-
-You should be able to do this by just copying in a skeleton template and
-then doing a quick fix up of the version numbers.
-
-Then commit the move and the new file.
+    $ (edit pod/.gitignore )
+    $ git add pod/.gitignore
 
-For example, assuming you just released 5.10.1:
+Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>,
+and edit the moved delta file to change the C<NAME> from C<perldelta> to
+C<perlNNNdelta>.  For example, assuming you just released 5.10.1, and are
+about to create the 5.10.2 perldelta:
 
+    $ rm  pod/perl5101delta.pod # remove the auto-generated file, if any
     $ git mv pod/perldelta.pod pod/perl5101delta.pod
     $ (edit pod/perl5101delta.pod to retitle)
     $ git add pod/perl5101delta.pod
 
+Then create a new empty perldelta.pod file for the new release; see
+F<Porting/how_to_write_a_perldelta.pod>. You should be able to do this by
+just copying in a skeleton template and then doing a quick fix up of the
+version numbers.  Then commit the move and the new file.
+
     $ cp -i Porting/perldelta_template.pod pod/perldelta.pod
     $ (edit pod/perldelta.pod)
     $ git add pod/perldelta.pod
     $ git commit -m 'create perldelta for 5.10.2'
 
-Now you need to update various tables of contents, most of which can be
-generated automatically.
+=item *
+
+Now you need to update various tables of contents related to perldelta,
+most of which can be generated automatically.
 
 Edit F<pod.lst>: add the new entry, flagged as 'd', and unflag the previous
 entry from being 'd'; for example:
@@ -926,6 +937,12 @@ entry from being 'd'; for example:
     +d perl5102delta                Perl changes in version 5.10.2
     +  perl5101delta                Perl changes in version 5.10.1
 
+Manually create a temporary link to the new delta file; normally this is
+done from the Makefile, but the Makefile is updated by buildtoc, and
+buildtoc won't run without the file there:
+
+    $ ln -s perldelta.pod pod/perl5102delta.pod
+
 Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
 the following files:
 
@@ -942,7 +959,7 @@ Finally, commit:
     $ git commit -a -m 'update TOC for perlNNNdelta'
 
 At this point you may want  to compare the commit with a previous bump to
-see if they look similar. See commit 2b6e134265 for an example of a
+see if they look similar. See commit 8891dd8d for an example of a
 previous version bump.
 
 =item *
@@ -950,16 +967,32 @@ previous version bump.
 I<You MUST SKIP this step for RC, BLEAD>
 
 If this was the first release of a new maint series, (5.x.0 where x is
-even), 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.
+even) then bump the version in the blead branch in git, e.g. 5.12.0 to
+5.13.0.
+
+First, add a new feature bundle to F<lib/feature.pm>, initially by just
+copying the exiting entry, and bump the file's $VERSION; e.g.
+
+        "5.14" => [qw(switch say state unicode_strings)],
+    +    "5.15" => [qw(switch say state unicode_strings)],
 
-[ XXX probably lots more stuff to do, including perldelta,
-C<lib/feature.pm> ]
+Then follow the item "Bump the version number" in the section
+L<"Building a release - advance actions"> to bump the version in the
+remaining files and test and commit.
+
+Finally, push the changes.
+
+=item *
+
+I<You MUST SKIP this step for RC, BLEAD>
+
+If this was the first release of a new maint series, (5.x.0 where x is
+even), then create a new maint branch based on the commit tagged as
+the current release.
 
 Assuming you're using git 1.7.x or newer:
 
-    $ git checkout -b maint-5.12
+    $ git checkout -b maint-5.12 v5.12.0
     $ git push origin -u maint-5.12
 
 =item *