This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
release_managers_guide.pod: amended based on v5.19.1 experience
authorDavid Golden <dagolden@cpan.org>
Fri, 21 Jun 2013 14:02:07 +0000 (10:02 -0400)
committerDavid Golden <dagolden@cpan.org>
Fri, 21 Jun 2013 14:28:46 +0000 (10:28 -0400)
Porting/release_managers_guide.pod

index 0995866..a66c5c3 100644 (file)
@@ -195,9 +195,9 @@ To see which core distro versions differ from the current CPAN versions:
 
     $ ./perl -Ilib Porting/core-cpan-diff -x -a
 
-Passing C<-u cpan> (and maybe C<-u undef>) will probably be helpful, since
-those are the only types of distributions that you can actually affect as a
-perl release manager (as opposed to a CPAN module maintainer).
+However, this only checks whether the version recorded in
+F<Porting/Maintainers.pl> differs from the latest on CPAN.  It doesn't tell you
+if the code itself has diverged from CPAN.
 
 You can also run an actual diff of the contents of the modules, comparing core
 to CPAN, to ensure that there were no erroneous/extraneous changes that need to
@@ -205,13 +205,26 @@ be dealt with. You do this by not passing the C<-x> option:
 
     $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
 
-then fix the core, or cajole CPAN authors as appropriate. See also the C<-d>
-and C<-v> options for more detail (and the C<-u> option as mentioned above).
-You'll probably want to use the C<-c cachedir> option to avoid repeated CPAN
-downloads and may want to use C<-m file:///mirror/path> if you made a local
-CPAN mirror. Note that a minicpan mirror won't actually work, but can provide a
-good first pass to quickly get a list of modules which definitely haven't
-changed, to avoid having to download absolutely everything.
+Passing C<-u cpan> (and maybe C<-u undef>) will probably be helpful, since
+it limits the search to distributions with those upstream sources.  (It's
+OK for blead upstream to differ from CPAN because those dual-life releases
+usually come I<after> perl is released.
+
+See also the C<-d> and C<-v> options for more detail (and the C<-u> option as
+mentioned above).  You'll probably want to use the C<-c cachedir> option to
+avoid repeated CPAN downloads and may want to use C<-m file:///mirror/path> if
+you made a local CPAN mirror. Note that a minicpan mirror won't actually work,
+but can provide a good first pass to quickly get a list of modules which
+definitely haven't changed, to avoid having to download absolutely everything.
+
+For a BLEAD release with 'cpan' upstream, if a CPAN release appears to be ahead
+of blead, then consider updating it (or asking the relevant porter to do so).
+If blead contains edits to a 'cpan' upstream module, this is naughty but
+sometimes unavoidable to keep blead tests passing.  Make sure the affected file
+has a CUSTOMIZED entry in F<Porting/Maintainers.pl>.  For 'undef' upstream,
+you'll have to use your judgment for whether any delta should be ignored (like
+'blead' upstream) or treated like a 'cpan' upstream and flagged.  Ask around on
+#p5p if you're not sure.
 
 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
@@ -352,6 +365,9 @@ Read  F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
 every section it lists is, if necessary, populated and complete. Copy
 edit the whole document.
 
+You won't be able to automatically fill in the "Updated Modules" section until
+after Module::CoreList is updated (as described below in
+L<"update Module::CoreList">).
 
 =head3 Bump the version number
 
@@ -467,6 +483,12 @@ L<perlport> has a section currently named I<Supported Platforms> that
 indicates which platforms are known to build in the current release.
 If necessary update the list and the indicated version number.
 
+=head3 check a readonly build
+
+Even before other prep work, follow the steps in  L<build the tarball> and test
+it locally.  Because a perl source tarballs sets many files read-only, it could
+test differently than tests run from the repository.  After you're sure
+permissions aren't a problem, delete the generated directory and tarballs.
 
 
 =head2 Building a release - on the day
@@ -492,81 +514,9 @@ those cases. Create the branch by running
   git checkout -b release-5.xx.yy
 
 
-=head3 finalize perldelta
-
-Finalize the perldelta.  In particular, fill in the Acknowledgements
-section, which can be generated with something like:
-
-  $ perl Porting/acknowledgements.pl v5.15.0..HEAD
-
-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/perldelta.pod
-    $ spell pod/perldelta.pod
-
-Also, you may want to generate and view an HTML version of it to check
-formatting, e.g.
-
-    $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > /tmp/perldelta.html
-
-Another good HTML preview option is http://search.cpan.org/pod2html
-
-If you make changes, be sure to commit them.
-
-=for checklist skip BLEAD-POINT MAINT RC
-
-=head3 remove stale perldeltas
-
-For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas
-from the BLEAD-POINT releases since the previous BLEAD_FINAL should have
-now been consolidated into the current perldelta, and hence are now just
-useless clutter.  They can be removed using:
-
-    $ git rm <file1> <file2> ...
-
-For example, for RC0 of 5.16.0:
-
-    $ cd pod
-    $ git rm perldelta515*.pod
-
-=for checklist skip BLEAD BLEAD-POINT
-
-=head3 add recent perldeltas
-
-For the first RC for a MAINT release, copy in any recent perldeltas from
-blead that have been added since the last release on this branch. This
-should include any recent maint releases on branches older than your one,
-but not newer. For example if you're producing a 5.14.x release, copy any
-perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from
-5.16.x or higher. Remember to
-
-    $ git add <file1> <file2> ...
-
-=head3 update and commit perldelta files
-
-If you have added or removed any perldelta files via the previous two
-steps, then edit F<pod/perl.pod> to add/remove them from its table of
-contents, then run F<Porting/pod_rules.pl> to propagate your changes there
-into all the other files that mention them (including F<MANIFEST>). You'll
-need to C<git add> the files that it changes.
-
-Then build a clean perl and do a full test
-
-    $ git status
-    $ git clean -dxf
-    $ ./Configure -Dusedevel -des
-    $ make
-    $ make test
-
-Once all tests pass, commit your changes.
-
 =head3 build a clean perl
 
-If you skipped the previous step (adding/removing perldeltas)
-make sure you have a gitwise-clean perl directory (no modified files,
+Make sure you have a gitwise-clean perl directory (no modified files,
 unpushed commits etc):
 
     $ git status
@@ -611,9 +561,8 @@ Then change to your perl checkout, and if necessary,
 
     $ make
 
-If this is not the first update for this version (e.g. if it was updated
-when the version number was originally bumped), first edit
-F<dist/Module-CoreList/lib/Module/CoreList.pm> to delete the existing
+Before updating Module::CoreList, first edit
+F<dist/Module-CoreList/lib/Module/CoreList.pm> and delete any 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.
 
@@ -637,6 +586,9 @@ Check that file over carefully:
 
     $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
 
+XXX I'm not sure if this updates Module::CoreList::Utils, so double
+check that file carefully.
+
 =head4 Bump C<$Module::CoreList::VERSION>
 
 If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this for
@@ -706,6 +658,97 @@ cherry-pick it back).
 
     $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod
 
+=head4 Rebuild and test
+
+Build and test to get the changes into the currently built lib directory and to ensure
+all tests are passing.
+
+=head3 finalize perldelta
+
+Finalize the perldelta.  In particular, fill in the Acknowledgements
+section, which can be generated with something like:
+
+  $ perl Porting/acknowledgements.pl v5.15.0..HEAD
+
+Fill in the "Updated Modules" section now that Module::CoreList is updated.
+
+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/perldelta.pod
+    $ spell pod/perldelta.pod
+
+Also, you may want to generate and view an HTML version of it to check
+formatting, e.g.
+
+    $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > /tmp/perldelta.html
+
+Another good HTML preview option is http://search.cpan.org/pod2html
+
+If you make changes, be sure to commit them.
+
+=for checklist skip BLEAD-POINT MAINT RC
+
+=head3 remove stale perldeltas
+
+For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas
+from the BLEAD-POINT releases since the previous BLEAD_FINAL should have
+now been consolidated into the current perldelta, and hence are now just
+useless clutter.  They can be removed using:
+
+    $ git rm <file1> <file2> ...
+
+For example, for RC0 of 5.16.0:
+
+    $ cd pod
+    $ git rm perldelta515*.pod
+
+=for checklist skip BLEAD BLEAD-POINT
+
+=head3 add recent perldeltas
+
+For the first RC for a MAINT release, copy in any recent perldeltas from
+blead that have been added since the last release on this branch. This
+should include any recent maint releases on branches older than your one,
+but not newer. For example if you're producing a 5.14.x release, copy any
+perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from
+5.16.x or higher. Remember to
+
+    $ git add <file1> <file2> ...
+
+=head3 update and commit perldelta files
+
+If you have added or removed any perldelta files via the previous two
+steps, then edit F<pod/perl.pod> to add/remove them from its table of
+contents, then run F<Porting/pod_rules.pl> to propagate your changes there
+into all the other files that mention them (including F<MANIFEST>). You'll
+need to C<git add> the files that it changes.
+
+Then build a clean perl and do a full test
+
+    $ git status
+    $ git clean -dxf
+    $ ./Configure -Dusedevel -des
+    $ make
+    $ make test
+
+Once all tests pass, commit your changes.
+
+=head3 build a clean perl
+
+If you skipped the previous step (adding/removing perldeltas),
+again, make sure you have a gitwise-clean perl directory (no modified files,
+unpushed commits etc):
+
+    $ git status
+    $ git clean -dxf
+
+then configure and build perl so that you have a Makefile and porting tools:
+
+    $ ./Configure -Dusedevel -des && make
+
 =for checklist skip BLEAD BLEAD-POINT
 
 =head3 synchronise from blead's perlhist.pod
@@ -801,6 +844,9 @@ Then delete the temporary installation.
 
 =head3 push the work so far
 
+XXX why do we need to do this if we're working on a release branch
+anyway?
+
 Push all your recent commits:
 
     $ git push origin release-5.xx.yy
@@ -966,6 +1012,9 @@ report. Check that it shows up, then remember to close it!
 
 =head3 monitor smokes
 
+XXX This is probably irrelevant if working on a release branch, though
+MAINT or RC might want to push a smoke branch and wait.
+
 Wait for the smoke tests to catch up with the commit which this release is
 based on (or at least the last commit of any consequence).
 
@@ -1004,16 +1053,15 @@ may need to contact a PAUSE administrator or even bump the version of perl.
 
 Upload both the .gz and .bz2 versions of the tarball.
 
-Do not proceed any further until you are sure that your tarballs are on
-CPAN.  Check your authors directory on one of the "fast" CPAN mirrors
-(e.g., cpan.hexten.net
-or cpan.cpantesters.org) to confirm that your uploads have been successful.
+Do not proceed any further until you are sure that your tarballs are on CPAN.
+Check your authors directory www.cpan.org (the globally balanced "fast"
+mirror) to confirm that your uploads have been successful.
 
-=for checklist skip RC
+=for checklist skip RC BLEAD-POINT
 
 =head3 wait for indexing
 
-I<You MUST SKIP this step for RC>
+I<You MUST SKIP this step for RC and BLEAD-POINT>
 
 Wait until you receive notification emails from the PAUSE indexer
 confirming that your uploads have been received.  IMPORTANT -- you will
@@ -1225,6 +1273,8 @@ receive its changes.
 
 And nag the sysadmins to make this directory available via rsync.
 
+XXX Who are the sysadmins?  Contact info?
+
 =for checklist skip BLEAD-POINT RC
 
 =head3 copy perldelta.pod to blead
@@ -1252,6 +1302,8 @@ Finally, commit:
 
 =head3 copy perlhist.pod entries to blead
 
+XXX probably irrelevant for BLEAD-POINT
+
 Make sure any recent F<pod/perlhist.pod> entries are copied to
 F<perlhist.pod> on blead.  e.g.
 
@@ -1261,9 +1313,9 @@ F<perlhist.pod> on blead.  e.g.
 =head3 bump RT version number
 
 Log into http://rt.perl.org/ and check whether the new version is in the RT
-fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is
-to go to L<https://rt.perl.org/rt3/Search/Build.html> and click on the drop
-downs next to the C<Perl Version> and C<Fixed In> labels.
+fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is to
+open up any ticket for modification and check the drop downs next to the
+C<Perl Version> and C<Fixed In> labels.
 
 If the new version is not listed there, send an email to C<perlbug-admin at
 perl.org> requesting this.
@@ -1310,9 +1362,10 @@ to ensure that the tarballs are available on the website.
 Check C</src> on CPAN (on a fast mirror) to ensure that links to
 the new tarballs have appeared.  There should be links in C</src/5.0>
 (which is accumulating all new versions), and an appropriate mention in
-C</src> (which describes the latest versions in each branch, with links).
+C</src/README.html> (which describes the latest versions in each branch,
+with links). BLEAD-POINT releases will not be mentioned.
 
-These links should appear automatically, some hours after upload.
+The C</src/5.0> links should appear automatically, some hours after upload.
 If they don't, or the C</src> description is inadequate,
 ask Ask <ask@perl.org>.
 
@@ -1345,6 +1398,12 @@ mail Leo as last resort.
 
 This repository can be found on L<github|https://github.com/perlorg/perlweb>.
 
+=head3 update release manager's guide
+
+Go over your notes from the release (you did take some, right?) and update
+F<Porting/release_managers_guide.pod> with any fixes or information that
+will make life easier for the next release manager.
+
 =for checklist end
 
 =head1 SOURCE