X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/6d5e92cd815e54c7272b7f63bc855bc25943ce9e..7ac0c33863364a2c29767a548fa0fc588e55d7cb:/Porting/release_managers_guide.pod
diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 424e31a..e684860 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:
@@ -65,7 +65,7 @@ The checklist of a typical release cycle is as follows:
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.
@@ -96,6 +96,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 +149,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
@@ -153,6 +167,12 @@ 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
+
+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.
+
=for checklist skip RC
=head3 Quotation for release announcement epigraph
@@ -164,34 +184,129 @@ 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.
+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).
-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
+
+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.
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<@IGNORE> 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