X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/819435defd4f2d5a07321d1b1f607f94e239035e..58f4626762668e1c1948832073998af84b2c85d0:/Porting/release_managers_guide.pod
diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 0653c55..ceee995 100644
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -15,14 +15,14 @@ document that starts with a checklist for your release.
This script is run as:
- perl Porting/make-rmg-checklist \
- --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod
+ perl Porting/make-rmg-checklist \
+ --version [5.x.y-RC#] > /tmp/rmg.pod
You can also pass the C<--html> flag to generate an HTML document instead of
POD.
- perl Porting/make-rmg-checklist --html \
- --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html
+ perl Porting/make-rmg-checklist --html \
+ --version [5.x.y-RC#] > /tmp/rmg.html
=head1 SYNOPSIS
@@ -46,16 +46,16 @@ The checklist of a typical release cycle is as follows:
...time passes...
a few weeks before the release, a number of steps are performed,
- including bumping the version to 5.10.2
+ 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 is released
post-release actions are performed, including creating new
- perldelta.pod
+ perldelta.pod
... the cycle continues ...
@@ -141,16 +141,10 @@ Andreas' email address at:
https://pause.perl.org/pause/query?ACTION=pause_04imprint
-=head3 search.cpan.org pumpkin status
-
-Make sure that search.cpan.org knows that you're allowed to upload
-perl distros. Contact Graham Barr to make sure that you're on the right
-list.
-
=head3 rt.perl.org update access
Make sure you have permission to close tickets on L
-so you can respond to bug report as necessary during your stint. If you
+so you can respond to bug reports as necessary during your stint. If you
don't, make an account (if you don't have one) and contact the pumpking
with your username to get ticket-closing permission.
@@ -165,20 +159,31 @@ release. Have a chat with whichever evil perl porter tried to talk
you into the idea in the first place to figure out the best way to
resolve the issue.
-=head3 git clone of https://github.com/perlorg/perlweb
+=head3 web-based file share
-For updating the L web pages, either a Github account or
-sweet-talking somebody with a Github account into obedience is needed. This
-is only needed on the day of the release or shortly afterwards.
+You will need to be able to share tarballs with #p5p members for
+pre-release testing, and you may wish to upload to PAUSE via URL.
+Make sure you have a way of sharing files, such as a web server or
+file-sharing service.
-=for checklist skip RC
+Porters have access to the "dromedary" server (users.perl5.git.perl.org),
+which has a F directory to share files with.
+(L)
+
+If you use Dropbox, you can append "raw=1" as a parameter to their usual
+sharing link to allow direct download (albeit with redirects).
=head3 Quotation for release announcement epigraph
-I
+You will need a quotation to use as an epigraph to your release announcement.
+It will live forever (along with Perl), so make it a good one.
+
+=head3 Install the previous version of perl
-For all except an RC release of perl, you will need a quotation
-to use as an epigraph to your release announcement.
+During the testing phase of the release you have created, you will be
+asked to compare the installed files with a previous install. Save yourself
+some time on release day, and have a (clean) install of the previous
+version ready.
=head2 Building a release - advance actions
@@ -201,12 +206,12 @@ 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
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 ~/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 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 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
@@ -215,14 +220,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.
-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. 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.
If you are making a MAINT release, run C on both blead and
maint, then diff the two outputs. Compare this with what you expect, and if
@@ -230,7 +238,26 @@ necessary, fix things up. For example, you might think that both blead
and maint are synchronised with a particular CPAN module, but one might
have some extra changes.
-=head3 How to sync a CPAN module with a cpan/ distro
+In any case, any cpan-first distribution that is listed as having files
+"Customized for blead" in the output of cpan-core-diff should have requests
+submitted to the maintainer(s) to make a cpan release to catch up with blead.
+
+Additionally, all files listed as "modified" but not "customized for blead"
+should have entries added under the C key in
+F, as well as checksums updated via:
+
+ cd t; ../perl -I../lib porting/customized.t --regen
+
+=head4 Sync CPAN modules with the corresponding cpanE distro
+
+In most cases, once a new version of a distribution shipped with core has been
+uploaded to CPAN, the core version thereof can be synchronized automatically
+with the program F. (But see the comments at the
+beginning of that program. In particular, it has not yet been exercised on
+Windows as much as it has on Unix-like platforms.)
+
+If, however, F does not provide good results, follow
+the steps below.
=over 4
@@ -251,7 +278,7 @@ C in the F directory.
=item *
Remove files we do not need. That is, remove any files that match the
-entries in C<@IGNORE> in F, and anything that
+entries in C<@IGNORABLE> in F, and anything that
matches the C section of the distro's entry in the C<%Modules>
hash.
@@ -265,7 +292,7 @@ into the repository anyway.
=item *
For any new files in the distro, determine whether they are needed.
-If not, delete them, and list them in either C or C<@INGORE>.
+If not, delete them, and list them in either C or C<@IGNORABLE>.
Otherwise, add them to C, and run C to add the files
to the repository.
@@ -294,7 +321,7 @@ Run the tests for the package.
=item *
-Run the tests in F.
+Run the tests in F (C).
=item *
@@ -313,50 +340,59 @@ If everything is ok, commit the changes.
For entries with a non-simple C section, or with a C