X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/a6836307311ae6667256d50a0fe9bc65ab3c5d75..33642846cd1f65854420097ae44b3c72298e44ef:/Porting/release_managers_guide.pod
diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 8af9d03..9da9300 100644
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -35,8 +35,8 @@ pumpking. Blead releases from 5.11.0 forward are made each month on the
20th by a non-pumpking release engineer. The release engineer roster
and schedule can be found in Porting/release_schedule.pod.
-This document both helps as a check-list for the release engineer
-and is a base for ideas on how the various tasks could be automated
+This document both helps as a check-list for the release engineer
+and is a base for ideas on how the various tasks could be automated
or distributed.
The checklist of a typical release cycle is as follows:
@@ -59,17 +59,15 @@ The checklist of a typical release cycle is as follows:
... the cycle continues ...
-
=head1 DETAILS
Some of the tasks described below apply to all four types of
release of Perl. (blead, RC, final release of maint, final
release of blead). Some of these tasks apply only to a subset
-of these release types. If a step does not apply to a given
+of these release types. If a step does not apply to a given
type of release, you will see a notation to that effect at
the beginning of the step.
-
=head2 Release types
=over 4
@@ -96,6 +94,13 @@ changes since.
It's essentially the same procedure as for making a release candidate, but
with a whole bunch of extra post-release steps.
+Note that for a maint release there are two versions of this guide to
+consider: the one in the maint branch, and the one in blead. Which one to
+use is a fine judgement. The blead one will be most up-to-date, while
+it might describe some steps or new tools that aren't applicable to older
+maint branches. It is probably best to review both versions of this
+document, but to most closely follow the steps in the maint version.
+
=item A blead point release (BLEAD-POINT)
A release with an odd version number, such as 5.15.0 or 5.15.1.
@@ -142,6 +147,13 @@ 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
+don't, make an account (if you don't have one) and contact the pumpking
+with your username to get ticket-closing permission.
+
=head3 git checkout and commit bit
You will need a working C installation, checkout of the perl
@@ -170,69 +182,179 @@ to use as an epigraph to your release announcement.
=head2 Building a release - advance actions
-The work of building a release candidate for a numbered release of
-perl generally starts several weeks before the first release candidate.
-Some of the following steps should be done regularly, but all I be
-done in the run up to a release.
+The work of building a release candidate for an even numbered release
+(BLEAD-FINAL) of perl generally starts several weeks before the first
+release candidate. Some of the following steps should be done regularly,
+but all I be done in the run up to a release.
=head3 dual-life CPAN module synchronisation
-Ensure that dual-life CPAN modules are synchronised with CPAN. Basically,
-run the following:
+To see which core distro versions differ from the current CPAN versions:
- $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
+ $ ./perl -Ilib Porting/core-cpan-diff -x -a
-to see any inconsistencies between the core and CPAN versions of distros,
-then fix the core, or cajole CPAN authors as appropriate. See also the
-C<-d> and C<-v> options for more detail. 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.
+However, this only checks whether the version recorded in
+F differs from the latest on CPAN. It doesn't tell you
+if the code itself has diverged from CPAN.
-To see which core distro versions differ from the current CPAN versions:
+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 -x -a
+ $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
+
+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
+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-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
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.
+have some extra changes.
+
+=head3 How to sync a CPAN module with a cpan/ distro
+
+=over 4
+
+=item *
+Fetch the most recent version from CPAN.
+
+=item *
+
+Unpack the retrieved tarball. Rename the old directory; rename the new
+directory to the original name.
+
+=item *
+
+Restore any F<.gitignore> file. This can be done by issuing
+C in the F directory.
+
+=item *
+
+Remove files we do not need. That is, remove any files that match the
+entries in C<@IGNORABLE> in F, and anything that
+matches the C section of the distro's entry in the C<%Modules>
+hash.
+
+=item *
+
+Restore any files mentioned in the C section, using
+C. Make any new customizations if necessary. Also,
+restore any files that are mentioned in C<@IGNORE>, but were checked
+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>.
+Otherwise, add them to C, and run C to add the files
+to the repository.
+
+=item *
+
+For any files that are gone, remove them from C, and use
+C to tell git the files will be gone.
+
+=item *
+
+If the C file was changed in any of the previous steps, run
+C.
+
+=item *
+
+For any files that have an execute bit set, either remove the execute
+bit, or edit F
+
+=item *
+
+Run C (or C on Windows), see if C compiles.
+
+=item *
+
+Run the tests for the package.
+
+=item *
+
+Run the tests in F.
+
+=item *
+
+Update the C entry in F.
+
+=item *
+
+Run a full configure/build/test cycle.
+
+=item *
+
+If everything is ok, commit the changes.
+
+=back
+
+For entries with a non-simple C section, or with a C