Update which stable release series are now "officially" supported

[perl5.git] / Porting / release_managers_guide.pod

diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index c1eeff1..873b475 100644 (file)
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -48,7 +48,7 @@ The checklist of a typical release cycle is as follows:
     a few weeks before the release, a number of steps are performed,
        including bumping the version to 5.10.2
 
     a few weeks before the release, a number of steps are performed,
        including bumping the version to 5.10.2
 

-    ...a few weeks passes...
+    ...a few weeks pass...

 
     perl-5.10.2-RC1 is released
 
 
     perl-5.10.2-RC1 is released
 


@@ -203,10 +203,10 @@ be dealt with. You do this by not passing the C<-x> option:
 
     $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
 
 
     $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
 

-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.
+Passing C<-u cpan> will probably be helpful, since it limits the search to
+distributions with 'cpan' upstream source.  (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
 
 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


@@ -215,14 +215,17 @@ 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.
 
 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.
+For a BLEAD-POINT or BLEAD-FINAL 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). (However, if this is a BLEAD-FINAL release or one of
+the last BLEAD-POINT releases before it and hence blead is in some kind of
+"code freeze" state (e.g. the sequence might be "contentious changes freeze",
+then "user-visible changes freeze" and finally "full code freeze") then any
+CPAN module updates must be subject to the same restrictions, so it may not be
+possible to update all modules until after the BLEAD-FINAL release.) 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>.

 
 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
 
 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


@@ -251,7 +254,7 @@ C<git checkout .gitignore> in the F<cpan/Distro> directory.
 =item *
 
 Remove files we do not need. That is, remove any files that match the
 =item *
 
 Remove files we do not need. That is, remove any files that match the

-entries in C<@IGNORE> in F<Porting/Maintainer.pl>, and anything that
+entries in C<@IGNORABLE> in F<Porting/Maintainer.pl>, and anything that

 matches the C<EXCLUDED> section of the distro's entry in the C<%Modules>
 hash.
 
 matches the C<EXCLUDED> section of the distro's entry in the C<%Modules>
 hash.
 


@@ -393,6 +396,10 @@ some of which need to be left unchanged.
 The line in F<INSTALL> about "is binary incompatible with" requires a
 correct choice of earlier version to declare incompatibility with.
 
 The line in F<INSTALL> about "is binary incompatible with" requires a
 correct choice of earlier version to declare incompatibility with.
 

+For the first RC release leading up to a BLEAD-FINAL release, update the
+description of which releases are now "officially" supported in
+F<pod/perlpolicy.pod>.
+

 When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
 C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
 you're releasing, unless you're absolutely sure the release you're about to
 When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
 C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
 you're releasing, unless you're absolutely sure the release you're about to


@@ -606,7 +613,7 @@ Add a perldelta entry for the new Module::CoreList version.
 
 =head4 Update C<%Module::CoreList::released> and C<CAVEATS>
 
 
 =head4 Update C<%Module::CoreList::released> and C<CAVEATS>
 

-In addition, if this is a final release (rather than a release candidate):
+For any release except an RC:

 
 =over 4
 
 
 =over 4
 


@@ -751,10 +758,9 @@ Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
 
     David    5.10.1       2009-Aug-06
 
 
     David    5.10.1       2009-Aug-06
 

-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>.
+List yourself in the left-hand column, and if this is the first release
+that you've ever done, make sure that your name is listed in the section
+entitled C<THE KEEPERS OF THE PUMPKIN>.

 
 I<If you're making a BLEAD-FINAL release>, also update the "SELECTED
 RELEASE SIZES" section with the output of
 
 I<If you're making a BLEAD-FINAL release>, also update the "SELECTED
 RELEASE SIZES" section with the output of


@@ -846,8 +852,9 @@ Create a tarball. Use the C<-s> option to specify a suitable suffix for
 the tarball and directory name:
 
  $ cd root/of/perl/tree
 the tarball and directory name:
 
  $ cd root/of/perl/tree

- $ make distclean
+ $ make distclean       # make sure distclean works

  $ git clean -xdf       # make sure perl and git agree on files
  $ git clean -xdf       # make sure perl and git agree on files

+                        # git clean should not output anything!

  $ git status           # and there's nothing lying around
 
  $ perl Porting/makerel -b -s RC1            # for a release candidate
  $ git status           # and there's nothing lying around
 
  $ perl Porting/makerel -b -s RC1            # for a release candidate


@@ -892,6 +899,9 @@ Check that basic configuration and tests work on each test machine:
 
     $ ./Configure -des && make all test
 
 
     $ ./Configure -des && make all test
 

+    # Or for a development release:
+    $ ./Configure -Dusedevel -des && make all test
+

 =head4 Run the test harness and install
 
 Check that the test harness and install work on each test machine:
 =head4 Run the test harness and install
 
 Check that the test harness and install work on each test machine:


@@ -937,6 +947,9 @@ Bootstrap the CPAN client on the clean install:
 
     $ bin/cpan
 
 
     $ bin/cpan
 

+    # Or, perhaps:
+    $ bin/cpan5.xx.x
+

 =head4 Install the Inline module with CPAN and test it
 
 Try installing a popular CPAN module that's reasonably complex and that
 =head4 Install the Inline module with CPAN and test it
 
 Try installing a popular CPAN module that's reasonably complex and that


@@ -1084,9 +1097,9 @@ earlier too (e.g.):
 =head3 update epigraphs.pod
 
 Add your quote to F<Porting/epigraphs.pod> and commit it.
 =head3 update epigraphs.pod
 
 Add your quote to F<Porting/epigraphs.pod> and commit it.

-Your release announcement will probably not have reached the web-visible
-archives yet, so you won't be able to include the customary link to the
-release announcement yet.
+You can include the customary link to the release announcement even before your
+message reaches the web-visible archives by looking for the X-List-Archive
+header in your message after receiving it back via perl5-porters.

 
 =head3 blog about your epigraph
 
 
 =head3 blog about your epigraph
 


@@ -1252,6 +1265,9 @@ Copy the perldelta.pod for this release into blead; for example:
  $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod  # for example
  $ git add pod/perl5101delta.pod
 
  $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod  # for example
  $ git add pod/perl5101delta.pod
 

+Don't forget to set the NAME correctly in the new file (e.g. perl5101delta
+rather than perldelta).
+

 Edit F<pod/perl.pod> to add an entry for the file, e.g.:
 
     perl5101delta              Perl changes in version 5.10.1
 Edit F<pod/perl.pod> to add an entry for the file, e.g.:
 
     perl5101delta              Perl changes in version 5.10.1