Update Porting/release_managers_guide.pod and Porting/makerel

In the course of releasing perl-5.11.5 I found a few things that are not
quite correct or no longer relevant:

- Add comments on the problems with doing this on Win32
- There are no longer Roman numerals in README.vms (since eb505c2afb6b5ac2aaba7935878ae6494d44732a)
- Note that Module::CoreList's Changes and META.yml files need updating too
- Fix Porting/makerel's null device redirection

One bigger problem remains to be resolved: when run in a normal cmd.exe
shell on Win32, the Porting/makerel script currently generates tarballs
containing world-writable files and directories, which the PAUSE indexer
then rejects as a possible security risk.

2 files changed, 38 insertions, 9 deletions

diff --git a/Porting/makerel b/Porting/makerel
index e4dfdefbc7..d0bf4eff95 100644
--- a/Porting/makerel
+++ b/Porting/makerel
@@ -3,6 +3,20 @@
 # A tool to build a perl release tarball
 # Very basic but functional - if you're on a unix system.
 #
+# If you're on Win32 then it should still work, but various Unix command-line
+# tools will need to be available somewhere. An obvious choice is to install
+# Cygwin and ensure its 'bin' folder is on the PATH in the shell where you run
+# this script. The Cygwin 'bin' folder needs to precede the Windows 'system32'
+# folder so that Cygwin's 'find' command is found in preference to the Windows
+# 'find' command. Your Cygwin installation will need to contain at least the
+# 'cpio' command, in addition to the commands installed by default, and it will
+# also be useful to have 'curl' and 'diffstat' installed too for later stages
+# of the release process (namely, Porting\corelist.pl and generating the commit
+# statistics for the perlXYZdelta.pod file respectively). Finally, ensure that
+# the 'awk' and 'shasum' commands are copies of gawk.exe and sha1sum.exe
+# respectively, rather the links to them that only work in a Cygwin bash shell
+# which they are by default.
+#
 # No matter how automated this gets, you'll always need to read
 # and re-read pumpkin.pod and release_managers_guide.pod to
 # check for things to be done at various stages of the process.
@@ -189,8 +203,9 @@ print "\n";
 system("ls -ld $perl*");
 print "\n";
 
+my $null = $^O eq 'MSWin32' ? 'NUL' : '/dev/null';
 for my $sha (qw(sha1 shasum sha1sum)) {
-    if (`which $sha 2>/dev/null`) {
+    if (`which $sha 2>$null`) {
 	system("$sha $perl*.tar.*");
 	last;
     }
diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index b63f858b12..6b7de3d931 100644
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -303,10 +303,6 @@ this line in README.vms needs special handling:
 
     rename perl-5^.10^.1.dir perl-5_10_1.dir
 
-Have a look a couple lines up from that. You'll see roman numerals.
-Update those too. Find someone with VMS clue if you have to update 
-the Roman numerals for a .0 release.
-
 Commit your changes:
 
     $ git st
@@ -460,7 +456,9 @@ 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.
+to C<wget> or C<curl> to fetch only package metadata remotely. (If you're
+on Win32, then installing Cygwin is one way to have commands like C<wget>
+and C<curl> available.)
 
 (If you'd prefer to have a full CPAN mirror, see 
 http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
@@ -502,6 +500,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.
 
+Also edit Module::CoreList's new version number in its F<Changes> file and
+in its F<META.yml> file.
+
 In addition, if this is a final release (rather than a release candidate):
 
 =over 4 
@@ -610,10 +611,13 @@ Push all your recent commits:
 
 I<You MUST SKIP this step for SNAPSHOT>
 
-Tag the release:
+Tag the release (e.g.):
 
     $ git tag v5.11.0 -m'First release of the v5.11 series!'
 
+(Adjust the syntax appropriately if you're working on Win32, i.e. use
+C<-m "..."> rather than C<-m'...'>.)
+
 It is VERY important that from this point forward, you not push
 your git changes to the Perl master repository.  If anything goes
 wrong before you publish your newly-created tag, you can delete
@@ -714,6 +718,10 @@ Bootstrap the CPAN client on the clean install:
 
     $ bin/perl -MCPAN -e'shell' 
 
+(Use C<... -e "shell"> instead on Win32. You probably also need a set of
+Unix command-line tools available for CPAN to function correctly without
+Perl alternatives like LWP installed. Cygwin is an obvious choice.)
+
 =item *
 
 Try installing a popular CPAN module that's reasonably complex and that
@@ -728,12 +736,18 @@ Check that your perl can run this:
     42
     $
 
+(Use C<... -lwe "use ..."> instead on Win32.)
+
 =item *
 
 Bootstrap the CPANPLUS client on the clean install:
 
     $ bin/cpanp
 
+(Again, on Win32 you'll need something like Cygwin installed, but make sure
+that you don't end up with its various F<bin/cpan*> programs being found on
+the PATH before those of the Perl that you're trying to test.)
+
 =item *
 
 Install an XS module, for example:
@@ -803,7 +817,7 @@ Upload both the .gz and .bz2 versions of the tarball.
 =item *
 
 Now that you've shipped the new perl release to PAUSE, it's
-time to publish the tag you created earlier to the public git repo:
+time to publish the tag you created earlier to the public git repo (e.g.):
 
     $ git push origin tag v5.11.0
 
@@ -855,7 +869,7 @@ to CPAN.
 
 I<You MUST SKIP this step for RC>
 
-Bump the perlXYZ version number.
+Bump the perlXYZdelta version number.
 
 First, create a new empty perlNNNdelta.pod file for the current release + 1;
 see F<Porting/how_to_write_a_perldelta.pod>.