more release_managers_guide tweaks
authorDavid Mitchell <davem@iabyn.com>
Sat, 22 Aug 2009 22:17:57 +0000 (23:17 +0100)
committerDavid Mitchell <davem@iabyn.com>
Sat, 22 Aug 2009 22:18:55 +0000 (23:18 +0100)
(cherry picked from commit 52a66c2cc3722485e8a16f1da9c026524180ca8c)

Porting/release_managers_guide.pod

index 1855d1a..4b33165 100644 (file)
@@ -148,8 +148,8 @@ in having one for a snapshot, but it's not required).
 
 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
 
@@ -171,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
@@ -262,11 +262,12 @@ 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
 
@@ -275,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
 
@@ -285,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
 
@@ -312,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 *
 
@@ -337,14 +346,6 @@ already in F<AUTHORS>
 
        $ git log | perl Porting/checkAUTHORS.pl --acknowledged AUTHORS -
 
-=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.
-
 =back
 
 =head2 Building a release - on the day
@@ -389,8 +390,7 @@ unpushed commits etc):
 If not already built, Configure and build perl so that you have a Makefile
 and porting tools:
 
-    $ ./Configure -Dusedevel -des
-    $ make
+    $ ./Configure -Dusedevel -des && make
 
 =item *
 
@@ -427,7 +427,7 @@ Commit META.yml if it has changed:
 
 I<You MUST SKIP this step for SNAPSHOT>
 
-Update C<Module::Corelist>.
+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
@@ -444,6 +444,14 @@ Then change to your perl checkout, and if necessary,
 
     $ make perl
 
+If this not the first update for this version, first edit
+F<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
@@ -452,20 +460,14 @@ Otherwise, run:
 
     $ ./perl -Ilib Porting/corelist.pl cpan
 
-This will chug for a while. Assuming all goes well, it will
-update F<lib/Module/CoreList.pm>.
+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<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
 appear in the final release, and leave as-is for the later RCs and final).
@@ -491,9 +493,7 @@ 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
-
+    $ git commit -m 'Update Module::CoreList for 5.x.y' lib/Module/CoreList.pm
 
 =item *
 
@@ -502,6 +502,7 @@ Check that the manifest is sorted and correct:
     $ make manisort
     $ make distclean
     $ perl Porting/manicheck
+    $ git status
 
 Commit MANIFEST if it has changed:
 
@@ -554,9 +555,19 @@ Build perl, then make sure it passes its own test suite, and installs:
 
 =item *
 
-Check that the output of C<perl -v> and C<perl -V> are as expected,
+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.
+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 *