Move Locale::Maketext::Simple from dist/ to cpan/
[p5sagit/p5-mst-13.2.git] / Porting / release_managers_guide.pod
index 2f7728e..60ef4ef 100644 (file)
@@ -2,11 +2,10 @@
 
 release_managers_guide - Releasing a new version of perl 5.x
 
-XXX as of Jul 2009, this file is still a work-in-progress. I think it
-contains all the actions needed to build a release, but things may have
-got skipped, and some things could do with polishing. Note that things
-change each release, there may be new things not covered here, or
-tools may need updating. DAPM
+As of August 2009, this file is mostly complete, although it is missing
+some detail on doing a major release (e.g. 5.10.0 -> 5.12.0). Note that
+things change at each release, so there may be new things not covered
+here, or tools may need updating.
 
 =head1 SYNOPSIS
 
@@ -68,7 +67,13 @@ the tarball will usually be the same as that of the previous release.
 
 =item Release Candidate (RC)
 
-XXX Describe me
+A release candidate is an attempt to produce a tarball that is a close as
+possible to the final release. Indeed, unless critical faults are found
+during the RC testing, the final release will be identical to the RC
+barring a few minor fixups (updating the release date in F<perlhist.pod>,
+removing the RC status from F<patchlevel.h>, etc). If faults are found,
+then the fixes should be put into a new release candidate, never directly
+into a final release.
 
 =item Stable/Maint release
 
@@ -106,7 +111,7 @@ https://pause.perl.org/, login, then select 'upload file to CPAN'; there
 should be a "For pumpkings only: Send a CC" tickbox.  If not, ask Andreas
 König to add your ID to the list of people allowed to upload something
 called perl.  You can find Andreas' email address at:
-    
+
     https://pause.perl.org/pause/query?ACTION=pause_04imprint
 
 =item CPAN mirror
@@ -139,12 +144,12 @@ 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.
-Some of these should be done regularly, but all I<must> be done in the 
-runup to a release.
+Some of the following steps should be done regularly, but all I<must> be
+done in the run up to a release.
 
 =over 4
 
@@ -166,7 +171,7 @@ To see which core distro versions differ from the current CPAN versions:
 
     $ ./perl -Ilib Porting/core-cpan-diff -x -a
 
-if you are making a maint release, run C<core-cpan-diff> on both blead and
+If you are making a maint release, run C<core-cpan-diff> on both blead and
 maint, then diff the two outputs. Compare this with what you expect, and if
 necessary, fix things up. For example, you might think that both blead
 and maint are synchronised with a particular CPAN module, but one might
@@ -236,23 +241,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,16 +253,21 @@ 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
 edit; then you feed this list back and it applies the edits. So, first
-scan the source dir looking for likely  candidates:
+scan the source directory looking for likely candidates. The command line
+arguments are the old and new version numbers, and -s means scan:
 
     $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
 
-This produces a file containing a list of suggested edits, eg:
+This produces a file containing a list of suggested edits, e.g.:
 
     NetWare/Makefile
 
@@ -283,9 +276,10 @@ This produces a file containing a list of suggested edits, eg:
 
 i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
 Review the file carefully, and delete any -/+ line pairs that you don't
-want changing. Remember that this tool is largely just grepping for '5.10.0'
-or whatever, so it will generate false positives. Be careful not change
-text like "this was fixed in 5.10.0"! Then run:
+want changing. You can also edit just the C<+> line to change the
+suggested replacement text. Remember that this tool is largely just
+grepping for '5.10.0' or whatever, so it will generate false positives. Be
+careful not change text like "this was fixed in 5.10.0"! Then run:
 
     $ Porting/bump-perl-version -u < /tmp/scan
 
@@ -293,9 +287,9 @@ which will update all the files shown; then commit the changes.
 
 Be particularly careful with F<INSTALL>, which contains a mixture of
 C<5.10.0>-type strings, some of which need bumping on every release, and
-some of which need to be left. Also note that this tool currently only
-performs a single change per line, so in particular, this line in
-README.vms needs special handling:
+some of which need to be left unchanged. Also note that this tool
+currently only detects a single substitution per line: so in particular,
+this line in README.vms needs special handling:
 
     rename perl-5^.10^.1.dir perl-5_10_1.dir
 
@@ -320,20 +314,27 @@ not-yet created tag for the forthcoming release; e.g.
 Due to warts in the perforce-to-git migration, some branches require extra
 exclusions to avoid other branches being pulled in. Make sure you have the
 correct incantation: replace the not-yet-created tag with C<HEAD> and see
-if git log produces roughly the right number of commits across roughly the
-right time period.
-
+if C<git log> produces roughly the right number of commits across roughly the
+right time period (you may find C<git log --pretty=oneline | wc> useful).
 
 =item *
 
-Check some more build configurations, e.g.
+Check some more build configurations. The check that setuid builds and
+installs is for < 5.11.0 only.
+
+    $ sh Configure -Dprefix=/tmp/perl-5.x.y  -Uinstallusrbinperl \
+        -Duseshrplib -Dd_dosuid
+    $ make
+    $ LD_LIBRARY_PATH=`pwd` make test     # or similar for useshrplib
 
-     -Duseshrplib -Dd_dosuid
-     make suidperl
+    $ make suidperl
+    $ su -c 'make install'
+    $ ls -l .../bin/sperl
+    -rws--x--x 1 root root 69974 2009-08-22 21:55 .../bin/sperl
 
-Check that setuid installs works (for < 5.11.0 only).
-XXX any other configs?
+(Then delete the installation directory.)
 
+XXX think of other configurations that need testing.
 
 =item *
 
@@ -345,20 +346,66 @@ already in F<AUTHORS>
 
        $ git log | perl Porting/checkAUTHORS.pl --acknowledged AUTHORS -
 
+=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 *
 
 I<You MAY SKIP this step for SNAPSHOT>
 
-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.
+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.
+
+    $ podchecker -warnings -warnings pod/perl5101delta.pod
+    $ spell pod/perl5101delta.pod
+
+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 *
 
-Configure and build perl so that you have a Makefile and porting tools:
+Make sure you have a gitwise-clean perl directory (no modified files,
+unpushed commits etc):
 
-    $ ./Configure -Dusedevel -des
-    $ make
+    $ git status
+
+=item *
+
+If not already built, Configure and build perl so that you have a Makefile
+and porting tools:
+
+    $ ./Configure -Dusedevel -des && make
+
+=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 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 regen; make regen_perly'
 
 =item *
 
@@ -366,58 +413,178 @@ Rebuild META.yml:
 
     $ rm META.yml
     $ make META.yml
+    $ git diff
+
+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.
 
 Commit META.yml if it has changed:
 
-    $ git commit -m 'Updating META.yml in preparation for release of 5.x.y' META.yml
+    $ git commit -m 'Update META.yml' META.yml
+
+=item *
+
+I<You MUST SKIP this step for SNAPSHOT>
+
+Update C<Module::Corelist> with module version data for the new release.
+
+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.
+
+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,
+
+    $ make perl
+
+If this not the first update for this version, first edit
+F<ext/Module-CoreList/lib/Module/CoreList.pm> to delete the existing
+entries for this version from the C<%released> and C<%version> hashes:
+they will have a key like C<5.010001> for 5.10.1.
+
+XXX the edit-in-place functionality of Porting/corelist.pl should
+be fixed to handle this automatically.
+
+Then, If you have a local CPAN mirror, run:
+
+    $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
+
+Otherwise, run:
+
+    $ ./perl -Ilib Porting/corelist.pl cpan
+
+This will chug for a while, possibly reporting various warnings about
+badly-indexed CPABN modules unreltaed to the modules actually in core.
+Assuming all goes well, it will update
+F<ext/Module-CoreList/lib/Module/CoreList.pm>.
+
+Check that file over carefully:
+
+    $ git diff ext/Module-CoreList/lib/Module/CoreList.pm
+
+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
+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.
+
+In addition, if this is a final release (rather than a release candidate):
+
+=over 4 
+
+=item *
+
+Update this version's entry in the C<%released> hash with today's date.
+
+=item *
+
+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 'Update Module::CoreList for 5.x.y' ext/Module-CoreList/lib/Module/CoreList.pm
 
 =item *
 
 Check that the manifest is sorted and correct:
 
     $ make manisort
-    $ make distclean 
+    $ make distclean
     $ perl Porting/manicheck
-
+    $ git status
 
 Commit MANIFEST if it has changed:
 
-    $ git commit -m 'Updating MANIFEST in preparation for release of 5.x.y' MANIFEST
-
-
+    $ git commit -m 'Update MANIFEST' MANIFEST
 
 =item *
 
 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, e.g.:
 
-          5.8.9-RC1     2008-Nov-10
+    David    5.10.1-RC1    2009-Aug-06
 
-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>.
+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 'Updating perlhist in preparation for release of 5.x.y pod/perlhist.pod
+    $ git commit -m 'add new release to perlhist' pod/perlhist.pod
+
+=item *
+
+I<You MUST SKIP this step for SNAPSHOT>
+
+Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
+a final release, remove it. For example:
 
+     static const char * const local_patches[] = {
+             NULL
+    +        ,"RC1"
+             PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
+
+Be sure to commit your change:
+
+    $ git commit -m 'bump version to RCnnn' patchlevel.h
 
 =item *
 
 Build perl, then make sure it passes its own test suite, and installs:
 
+    $ git clean -xdf
+    $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
+
+    # or if it's an odd-numbered version:
     $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
+
     $ make test install
 
 =item *
 
+Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
+C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
+especially as regards version numbers, patch and/or RC levels, and @INC
+paths. Note that as they have been been built from a git working
+directory, they will still identify themselves using git tags and
+commits.
+
+Then delete the temporary installation.
+
+=item *
+
+If this is maint release, make sure F<Porting/mergelog> is saved and
+committed.
+
+=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:
 
     $ cd root/of/perl/tree
     $ make distclean
-    $ git clean -xdf           #  make sure perl and git agree on files
+    $ git clean -xdf           # make sure perl and git agree on files
+    $ git status               # and there's nothing lying around
 
     $ perl Porting/makerel -b -s `git describe` # for a snapshot
     $ perl Porting/makerel -b -s RC1            # for a release candidate
@@ -433,6 +600,12 @@ here
 
 =item *
 
+Clean up the temporary directory, e.g.
+
+    $ rm -rf ../perl-x.y.z-RC1
+
+=item *
+
 Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
 have access to.
 
@@ -453,7 +626,9 @@ Check that basic configuration and tests work on each test machine:
 
 Check that the test harness and install work on each test machine:
 
+    $ make distclean
     $ ./Configure -des -Dprefix=/install/path && make all test_harness install
+    $ cd /install/path
 
 =item *
 
@@ -466,112 +641,86 @@ which is why you should test from the tarball.
 
 =item *
 
-Bootstrap the CPAN client on the clean install:
+Run the Installation Verification Procedure utility:
 
-    $ ./bin/perl -MCPAN -e'shell' 
+    $ bin/perlivp
+    ...
+    All tests successful.
+    $
 
 =item *
 
-Install Inline.pm 
-
-    $ ./bin/perl -MCPAN -e'install Inline'
+Compare the pathnames of all installed files with those of the previous
+release (i.e. against the last installed tarball on this branch which you
+have previously verified using this same procedure). In particular, look
+for files in the wrong place, or files no longer included which should be.
+For example, suppose the about-to-be-released version is 5.10.1 and the
+previous is 5.10.0:
 
-Check that your perl can run this:
-
-    $ ./bin/perl -lwe 'use Inline C => "int answer() { return 42;} "; print answer'
+    cd installdir-5.10.0/
+    find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
+    cd installdir-5.10.1/
+    find . -type f | sort > /tmp/f2
+    diff -u /tmp/f[12]
 
 =item *
 
-Bootstrap the CPANPLUS client on the clean install:
-
-    $ ./bin/cpanp
+Bootstrap the CPAN client on the clean install:
 
+    $ bin/perl -MCPAN -e'shell' 
 
 =item *
 
-Install an XS module.
+Try installing a popular CPAN module that's reasonably complex and that
+has dependencies; for example:
 
-=item *
+    CPAN> install Inline
+    CPAN> quit
 
-If all is well, announce the snapshot to p5p. (For a release candidate,
-instead follow the further steps described later.)
+Check that your perl can run this:
 
+    $ bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f'
+    42
+    $
 
 =item *
 
+Bootstrap the CPANPLUS client on the clean install:
 
-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.
-
-    podchecker -warnings -warnings pod/perl5101delta.pod
-    spell pod/perl5101delta.pod
+    $ bin/cpanp
 
 =item *
 
-I<You MUST SKIP this step for SNAPSHOT>
+Install an XS module, for example:
 
-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 ]
+    CPAN Terminal> i DBI
+    CPAN Terminal> quit
+    $ bin/perl -MDBI -e 1
+    $
 
 =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
-from the maint directory, but edit the C<Corelist.pm> in I<blead> and
-subsequently cherry-pick it.
-
-corelist.pl uses ftp.funet.fi to verify information about dual-lifed
-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.
-
-If you have a local CPAN mirror, run:
-
-    $ perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
-
-Otherwise, run:
-
-    $ perl -Ilib Porting/corelist.pl cpan
-
-This will chug for a while. Assuming all goes well, it will
- update lib/Module/CoreList.pm. 
-
-Check that file over carefully:
-
-    $ git diff lib/Module/CoreList.pm
-
-
-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
-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):
-
-    Update this version's entry in the C<%released> hash with today's date.
-
-Finally, commit the new version of Module::CoreList:
-
-    $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \
-     lib/Module/Corelist.pm
+I<You MAY SKIP this step for SNAPSHOT>
 
+Check that the C<perlbug> utility works. Try the following:
 
-=item *
+    $ bin/perlbug
+    ...
+    Subject: test bug report
+    Local perl administrator [yourself]: 
+    Editor [vi]: 
+    Module: 
+    Category [core]: 
+    Severity [low]: 
+    (edit report)
+    Action (Send/Display/Edit/Subject/Save to File): f
+    Name of file to save message in [perlbug.rep]: 
+    Action (Send/Display/Edit/Subject/Save to File): q
 
-Disarm the patchlevel.h change [ XXX expand ]
+and carefully examine the output (in F<perlbug.rep]>), especially
+the "Locally applied patches" section. If everything appears okay, then
+delete the file, and try it again, this time actually submitting the bug
+report. Check that it shows up, then remember to close it!
 
 =item *
 
@@ -592,19 +741,43 @@ 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.
 
-You may wish to create a .bz2 version of the tarball and upload that too.
+    https://pause.perl.org/
+
+(Login, then select 'Upload a file to CPAN')
+
+Upload both the .gz and .bz2 versions of the tarball.
 
 =item *
 
 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, for example:
 
-    $ 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 F<patchlevel.h> change; for example,
+
+     static const char * const local_patches[] = {
+             NULL
+    -        ,"RC1"
+             PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
+
+Be sure to commit your change:
+
+    $ git commit -m 'disarm RCnnn bump' patchlevel.h
+    $ git push origin ....
+
+
+=item *
+
 Mail p5p to announce your new release, with a quote you prepared earlier.
 
 =item *
@@ -617,50 +790,86 @@ do it for you.)
 
 =item *
 
+I<You MUST SKIP this step for SNAPSHOT>
+
+Ask Jarkko to add the tarball to http://www.cpan.org/src/
+
+=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/
+Ask Jarkko to update the descriptions of which tarballs are current in
+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. ]
+Remind the current maintainer of C<Module::CoreList> to push a new release
+to CPAN.
 
-In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
-entry as 'D',
+=item *
 
-Change perlNNNdelta references to the new version in these files
+I<You MUST SKIP this step for SNAPSHOT, RC>
 
-    INSTALL
-    win32/Makefile.mk
-    win32/Makefile
-    Makefile.SH
-    README
+Bump the perlXYZ version number.
 
-Also, edit the previous delta file to change the C<NAME> from C<perldelta>
-to C<perlNNNdelta>.
+First, create a new empty perlNNNdelta.pod file for the current release + 1;
+see F<Porting/how_to_write_a_perldelta.pod>.
 
-These two lists of files probably aren't exhaustive; do a recursive grep
-on the previous filename to look for suitable candidates.
+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, e.g.
 
-(see 16410843ea for an example).
+    $ cp -i Porting/perldelta_template pod/perl5102delta.pod
+    $ (edit it)
+    $ git add pod/perl5102delta.pod
 
-=item *
+Edit F<pod.lst>: add the new entry, flagged as 'D', and unflag the previous
+entry from being 'D'; for example:
 
-Run C<perl pod/buildtoc --build-all> to update the following files:
+    -D perl5101delta                Perl changes in version 5.10.1
+    +D perl5102delta                Perl changes in version 5.10.2
+    +  perl5101delta                Perl changes in version 5.10.1
+
+Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
+the following files:
 
     MANIFEST
+    Makefile.SH
+    pod.lst
     pod/perl.pod
-    win32/pod.mak
     vms/descrip_mms.template
+    win32/Makefile
+    win32/makefile.mk
+    win32/pod.mak
+
+Then manually edit (F<vms/descrip_mms.template> to bump the version
+in the following entry:
 
-If you modified perldelta.pod, (F<vms/descrip_mms.template> will
-needs a manual edit to bump the C<perldelta.pod> entry - it would
-be good for someone to figure out the fix.)
+    [.pod]perldelta.pod : [.pod]perl5101delta.pod
+
+XXX this previous step needs to fixed to automate it in pod/buildtoc.
+
+Manually update references to the perlNNNdelta version in these files:
+
+    INSTALL
+    README
+
+Edit the previous delta file to change the C<NAME> from C<perldelta>
+to C<perlNNNdelta>.
+
+These two lists of files probably aren't exhaustive; do a recursive grep
+on the previous filename to look for suitable candidates that may have
+been missed.
+
+Finally, commit:
+
+    $ git commit -a -m 'create perlXXXdelta'
+
+At this point you may want  to compare the commit with a previous bump to
+see if they look similar. See commit ca8de22071 for an example of a
+previous version bump.
 
 =item *
 
@@ -669,9 +878,6 @@ I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
 If this was a maint release, then edit F<Porting/mergelog> to change
 all the C<d> (deferred) flags to C<.> (needs review).
 
-XXX - we should be able to use git to automate much of the role
-previously filled by the mergelog.
-
 =item *
 
 I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
@@ -689,16 +895,23 @@ XXX need a git recipe
 
 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:
+Copy the perlNNNdelta.pod for this release into the other branches; for
+example:
 
-    MANIFEST
-    pod.lst
-    pod/perl.pod
-    vms/descrip_mms.template
-    win32/pod.mak
+    $ cp -i ../5.10.x/pod/perl5101delta.pod pod/    # for example
+    $ git add pod/perl5101delta.pod
+
+Edit F<pod.lst> to add an entry for the file, e.g.:
+
+    perl5101delta              Perl changes in version 5.10.1
+    
+Then rebuild various files:
+
+    $ perl pod/buildtoc --build-all
+
+Finally, commit:
 
-(see fc5be80860 for an example).
+    $ git commit -a -m 'add perlXXXdelta'
 
 =item *
 
@@ -714,13 +927,6 @@ 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>.