release_managers_guide - Releasing a new version of perl 5.x
-XXX as of Jul 2009, this file is still a work-in-progress. I think it
-contains all the actions needed to build a release, but things may have
-got skipped, and some things could do with polishing. Note that things
-change each release, there may be new things not covered here, or
-tools may need updating. DAPM
+As of August 2009, this file is mostly complete, although it is missing
+some detail on doing a major release (e.g. 5.10.0 -> 5.12.0). Note that
+things change at each release, so there may be new things not covered
+here, or tools may need updating.
=head1 SYNOPSIS
release candidate, or final, numbered release of maint or blead.
The release process has traditionally been executed by the current
-pumpking.
+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
=item Release Candidate (RC)
-XXX Describe me
+A release candidate is an attempt to produce a tarball that is a close as
+possible to the final release. Indeed, unless critical faults are found
+during the RC testing, the final release will be identical to the RC
+barring a few minor fixups (updating the release date in F<perlhist.pod>,
+removing the RC status from F<patchlevel.h>, etc). If faults are found,
+then the fixes should be put into a new release candidate, never directly
+into a final release.
=item Stable/Maint release
https://pause.perl.org/pause/query?ACTION=request_id
Check that your account is allowed to upload perl distros: goto
-https://pause.perl.org/, login, then select 'upload file to CPAN'; there
+L<https://pause.perl.org/>, login, then select 'upload file to CPAN'; there
should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas
König to add your ID to the list of people allowed to upload something
called perl. You can find Andreas' email address at:
https://pause.perl.org/pause/query?ACTION=pause_04imprint
+=item search.cpan.org
+
+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.
+
=item CPAN mirror
Some release engineering steps require a full mirror of the CPAN.
The work of building a release candidate for a numbered release of
perl generally starts several weeks before the first release candidate.
-Some of these should be done regularly, but all I<must> be done in the
-runup to a release.
+Some of the following steps should be done regularly, but all I<must> be
+done in the run up to a release.
=over 4
$ ./perl -Ilib Porting/core-cpan-diff -x -a
-if you are making a maint release, run C<core-cpan-diff> on both blead and
+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
necessary, fix things up. For example, you might think that both blead
and maint are synchronised with a particular CPAN module, but one might
Then run again without the -x option, to check that dual-life modules are
also sensible.
+ $ ./perl -Ilib Porting/cmpVERSION.pl -d ~/my_perl-tarballs/perl-5.10.0 .
+
=item *
I<You MAY SKIP this step for SNAPSHOT>
There is a tool to semi-automate this process. It works in two stages.
First, it generates a list of suggested changes, which you review and
edit; then you feed this list back and it applies the edits. So, first
-scan the source dir looking for likely candidates:
+scan the source directory looking for likely candidates. The command line
+arguments are the old and new version numbers, and -s means scan:
$ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
-This produces a file containing a list of suggested edits, eg:
+This produces a file containing a list of suggested edits, e.g.:
NetWare/Makefile
i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
Review the file carefully, and delete any -/+ line pairs that you don't
-want changing. Remember that this tool is largely just grepping for '5.10.0'
-or whatever, so it will generate false positives. Be careful not change
-text like "this was fixed in 5.10.0"! Then run:
+want changing. You can also edit just the C<+> line to change the
+suggested replacement text. Remember that this tool is largely just
+grepping for '5.10.0' or whatever, so it will generate false positives. Be
+careful not change text like "this was fixed in 5.10.0"! Then run:
$ Porting/bump-perl-version -u < /tmp/scan
-which will update all the files shown; then commit the changes.
+which will update all the files shown.
Be particularly careful with F<INSTALL>, which contains a mixture of
C<5.10.0>-type strings, some of which need bumping on every release, and
-some of which need to be left. Also note that this tool currently only
-performs a single change per line, so in particular, this line in
-README.vms needs special handling:
+some of which need to be left unchanged. Also note that this tool
+currently only detects a single substitution per line: so in particular,
+this line in README.vms needs special handling:
rename perl-5^.10^.1.dir perl-5_10_1.dir
+Have a look a couple lines up from that. You'll see roman numerals.
+Update those too. Find someone with VMS clue if you have to update
+the Roman numerals for a .0 release.
+
+Commit your changes:
+
+ $ git st
+ $ git diff
+ B<review the delta carefully>
+
+ $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
+
+When the version number is bumped, you should also update Module::CoreList (as
+described below in L<"Building a release - on the day">) to reflect the new
+version number.
=item *
all the changes in this release. You will need assume the existence of a
not-yet created tag for the forthcoming release; e.g.
- git log ... perl-5.10.0..perl5.12.0
+ git log ... perl-5.10.0..perl-5.12.0
Due to warts in the perforce-to-git migration, some branches require extra
exclusions to avoid other branches being pulled in. Make sure you have the
correct incantation: replace the not-yet-created tag with C<HEAD> and see
-if git log produces roughly the right number of commits across roughly the
-right time period.
-
+if C<git log> produces roughly the right number of commits across roughly the
+right time period (you may find C<git log --pretty=oneline | wc> useful).
=item *
-Check some more build configurations, e.g.
+Check some more build configurations. The check that setuid builds and
+installs is for < 5.11.0 only.
- -Duseshrplib -Dd_dosuid
- make suidperl
+ $ sh Configure -Dprefix=/tmp/perl-5.x.y -Uinstallusrbinperl \
+ -Duseshrplib -Dd_dosuid
+ $ make
+ $ LD_LIBRARY_PATH=`pwd` make test # or similar for useshrplib
+
+ $ make suidperl
+ $ su -c 'make install'
+ $ ls -l .../bin/sperl
+ -rws--x--x 1 root root 69974 2009-08-22 21:55 .../bin/sperl
-Check that setuid installs works (for < 5.11.0 only).
-XXX any other configs?
+(Then delete the installation directory.)
+XXX think of other configurations that need testing.
=item *
$ git log | perl Porting/checkAUTHORS.pl --acknowledged AUTHORS -
-=item *
-
-I<You MAY SKIP this step for SNAPSHOT>
-
-As there are no regular smokes [ XXX yet - please fix?] find out about the
-state of the current branch on VMS. If the branch you're releasing on
-is failing tests on VMS, you may not want to do a release.
-
=back
=head2 Building a release - on the day
If not already built, Configure and build perl so that you have a Makefile
and porting tools:
- $ ./Configure -Dusedevel -des
- $ make
+ $ ./Configure -Dusedevel -des && make
=item *
If any of the files managed by F<regen.pl> have changed, then you should
re-make perl to check that it's okay, then commit the updated versions:
- $ git commit -a -m 'make regn; make regn_perly'
+ $ git commit -a -m 'make regen; make regen_perly'
=item *
I<You MUST SKIP this step for SNAPSHOT>
-Update C<Module::Corelist>.
+Update C<Module::Corelist> with module version data for the new release.
Note that if this is a maint release, you should run the following actions
from the maint directory, but commit the C<Corelist.pm> changes in
$ make perl
+If this 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
+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.
+
+XXX the edit-in-place functionality of Porting/corelist.pl should
+be fixed to handle this automatically.
+
Then, If you have a local CPAN mirror, run:
$ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
$ ./perl -Ilib Porting/corelist.pl cpan
-This will chug for a while. Assuming all goes well, it will
-update F<lib/Module/CoreList.pm>.
+This will chug for a while, possibly reporting various warnings about
+badly-indexed CPAN modules unrelated to the modules actually in core.
+Assuming all goes well, it will update
+F<dist/Module-CoreList/lib/Module/CoreList.pm>.
Check that file over carefully:
- $ git diff lib/Module/CoreList.pm
-
-In particular, if this not the first update for this version, make sure
-that there isn't a duplicated entry (e.g. '5.010001' entries for both RC1
-and RC2).
-
-XXX the edit-in-place functionality of Porting/corelist.pl should
-be fixed to allow for this
+ $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
If necessary, bump C<$VERSION> (there's no need to do this for
every RC; in RC1, bump the version to a new clean number that will
(unless this is for maint; in which case commit it blead first, then
cherry-pick it back).
- $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \
- lib/Module/CoreList.pm
-
+ $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm
=item *
$ make manisort
$ make distclean
+ $ git clean -xdf # This shouldn't be necessary if distclean is correct
$ perl Porting/manicheck
+ $ git status
+
+ XXX manifest _sorting_ is now checked with make test_porting
Commit MANIFEST if it has changed:
=item *
-Check that the output of C<perl -v> and C<perl -V> are as expected,
+Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
+C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
especially as regards version numbers, patch and/or RC levels, and @INC
-paths.
+paths. Note that as they have been been built from a git working
+directory, they will still identify themselves using git tags and
+commits.
+
+Then delete the temporary installation.
+
+=item *
+
+If this is maint release, make sure F<Porting/mergelog> is saved and
+committed.
=item *
=item *
+I<You MUST SKIP this step for SNAPSHOT>
+
+Tag the release:
+
+ $ git tag v5.11.0 -m'First release of the v5.11 series!'
+
+It is VERY important that from this point forward, you not push
+your git changes to the Perl master repository. If anything goes
+wrong before you publish your newly-created tag, you can delete
+and recreate it. Once you push your tag, we're stuck with it
+and you'll need to use a new version number for your release.
+
+=item *
+
Create a tarball. Use the C<-s> option to specify a suitable suffix for
the tarball and directory name:
$ cd root/of/perl/tree
$ make distclean
- $ git clean -xdf # make sure perl and git agree on files
+ $ git clean -xdf # make sure perl and git agree on files
+ $ git status # and there's nothing lying around
$ perl Porting/makerel -b -s `git describe` # for a snapshot
$ perl Porting/makerel -b -s RC1 # for a release candidate
adds DOS line endings to some, then tars it up as
F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
+
XXX if we go for extra tags and branches stuff, then add the extra details
here
=item *
+Run the Installation Verification Procedure utility:
+
+ $ bin/perlivp
+ ...
+ All tests successful.
+ $
+
+=item *
+
+Compare the pathnames of all installed files with those of the previous
+release (i.e. against the last installed tarball on this branch which you
+have previously verified using this same procedure). In particular, look
+for files in the wrong place, or files no longer included which should be.
+For example, suppose the about-to-be-released version is 5.10.1 and the
+previous is 5.10.0:
+
+ cd installdir-5.10.0/
+ find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
+ cd installdir-5.10.1/
+ find . -type f | sort > /tmp/f2
+ diff -u /tmp/f[12]
+
+=item *
+
Bootstrap the CPAN client on the clean install:
- $ ./bin/perl -MCPAN -e'shell'
+ $ bin/perl -MCPAN -e'shell'
=item *
Check that your perl can run this:
- $ ./bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f'
+ $ bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f'
42
$
Bootstrap the CPANPLUS client on the clean install:
- $ ./bin/cpanp
+ $ bin/cpanp
=item *
CPAN Terminal> i DBI
CPAN Terminal> quit
$ bin/perl -MDBI -e 1
+ $
+=item *
+
+I<If you're building a SNAPSHOT, you should STOP HERE>
=item *
-I<You MAY SKIP this step for SNAPSHOT>
+Check that the C<perlbug> utility works. Try the following:
+
+ $ bin/perlbug
+ ...
+ Subject: test bug report
+ Local perl administrator [yourself]:
+ Editor [vi]:
+ Module:
+ Category [core]:
+ Severity [low]:
+ (edit report)
+ Action (Send/Display/Edit/Subject/Save to File): f
+ Name of file to save message in [perlbug.rep]:
+ Action (Send/Display/Edit/Subject/Save to File): q
+
+and carefully examine the output (in F<perlbug.rep]>), especially
+the "Locally applied patches" section. If everything appears okay, then
+delete the file, and try it again, this time actually submitting the bug
+report. Check that it shows up, then remember to close it!
+
+=item *
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).
=item *
-I<You MUST SKIP this step for SNAPSHOT>
-
Once smoking is okay, upload it to PAUSE. This is the point of no return.
If anything goes wrong after this point, you will need to re-prepare
a new release with a new minor version or RC number.
+ https://pause.perl.org/
+
+(Login, then select 'Upload a file to CPAN')
+
Upload both the .gz and .bz2 versions of the tarball.
=item *
-I<You MUST SKIP this step for SNAPSHOT>
-
-Create a tag for the exact git revision you built the release from.
-C<commit> below is the commit corresponding to the tarball. It can be
-omitted if there have been no further commits since the tarball was
-created.
+Now that you've shipped the new perl release to PAUSE, it's
+time to publish the tag you created earlier to the public git repo:
- $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' <commit>
- $ git push origin tag perl-5.10.1-RC1
+ $ git push origin tag v5.11.0
=item *
-I<You MUST SKIP this step for SNAPSHOT>
-
Disarm the F<patchlevel.h> change; for example,
static const char * const local_patches[] = {
Be sure to commit your change:
$ git commit -m 'disarm RCnnn bump' patchlevel.h
+ $ git push origin ....
=item *
=item *
-I<You MAY SKIP this step for SNAPSHOT>
-
Wait 24 hours or so, then post the announcement to use.perl.org.
(if you don't have access rights to post news, ask someone like Rafael to
do it for you.)
=item *
-I<You MUST SKIP this step for SNAPSHOT>
-
Ask Jarkko to add the tarball to http://www.cpan.org/src/
=item *
-I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
+I<You MUST SKIP this step for RC, BLEAD>
Ask Jarkko to update the descriptions of which tarballs are current in
http://www.cpan.org/src/README.html, and Rafael to update
=item *
-I<You MUST SKIP this step for SNAPSHOT, RC>
+I<You MUST SKIP this step for RC>
-Create a new empty perlNNNdelta.pod file for the current release + 1;
-see F<Porting/how_to_write_a_perldelta.pod>.
-[ XXX Perhaps we should have an empty template file we can copy in. ]
+Remind the current maintainer of C<Module::CoreList> to push a new release
+to CPAN.
-In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
-entry as 'D',
+=item *
-Change perlNNNdelta references to the new version in these files
+I<You MUST SKIP this step for RC>
- INSTALL
- win32/Makefile.mk
- win32/Makefile
- Makefile.SH
- README
+Bump the perlXYZ version number.
-Also, edit the previous delta file to change the C<NAME> from C<perldelta>
-to C<perlNNNdelta>.
+First, create a new empty perlNNNdelta.pod file for the current release + 1;
+see F<Porting/how_to_write_a_perldelta.pod>.
-These two lists of files probably aren't exhaustive; do a recursive grep
-on the previous filename to look for suitable candidates.
+You should be able to do this by just copying in a skeleton template and
+then doing a quick fix up of the version numbers, e.g.
-(see 16410843ea for an example).
+ $ cp -i Porting/perldelta_template.pod pod/perl5102delta.pod
+ $ (edit it)
+ $ git add pod/perl5102delta.pod
-=item *
+Edit F<pod.lst>: add the new entry, flagged as 'D', and unflag the previous
+entry from being 'D'; for example:
+
+ -D perl5101delta Perl changes in version 5.10.1
+ +D perl5102delta Perl changes in version 5.10.2
+ + perl5101delta Perl changes in version 5.10.1
-Run C<perl pod/buildtoc --build-all> to update the following files:
+Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
+the following files:
MANIFEST
+ Makefile.SH
+ pod.lst
pod/perl.pod
- win32/pod.mak
vms/descrip_mms.template
+ win32/Makefile
+ win32/makefile.mk
+ win32/pod.mak
+
+Then manually edit (F<vms/descrip_mms.template> to bump the version
+in the following entry:
+
+ [.pod]perldelta.pod : [.pod]perl5101delta.pod
-If you modified perldelta.pod, (F<vms/descrip_mms.template> will
-needs a manual edit to bump the C<perldelta.pod> entry - it would
-be good for someone to figure out the fix.)
+XXX this previous step needs to fixed to automate it in pod/buildtoc.
+
+Manually update references to the perlNNNdelta version in these files:
+
+ INSTALL
+ README
+
+Edit the previous delta file to change the C<NAME> from C<perldelta>
+to C<perlNNNdelta>.
+
+These two lists of files probably aren't exhaustive; do a recursive grep
+on the previous filename to look for suitable candidates that may have
+been missed.
+
+Finally, commit:
+
+ $ git commit -a -m 'create perlXXXdelta'
+
+At this point you may want to compare the commit with a previous bump to
+see if they look similar. See commit ca8de22071 for an example of a
+previous version bump.
=item *
-I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
+I<You MUST SKIP this step for RC, BLEAD>
If this was a maint release, then edit F<Porting/mergelog> to change
all the C<d> (deferred) flags to C<.> (needs review).
=item *
-I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
+I<You MUST SKIP this step for RC, BLEAD>
If this was a major release (5.x.0), then create a new maint branch
based on the commit tagged as the current release and bump the version
=item *
-I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
+I<You MUST SKIP this step for RC, BLEAD>
-Copy the perlNNNdelta.pod for this release into the other branches, and
-remember to update these files on those branches too:
+Copy the perlNNNdelta.pod for this release into the other branches; for
+example:
- MANIFEST
- pod.lst
- pod/perl.pod
- vms/descrip_mms.template
- win32/pod.mak
+ $ cp -i ../5.10.x/pod/perl5101delta.pod pod/ # for example
+ $ git add pod/perl5101delta.pod
-(see fc5be80860 for an example).
+Edit F<pod.lst> to add an entry for the file, e.g.:
-=item *
+ perl5101delta Perl changes in version 5.10.1
-I<You MUST SKIP this step for SNAPSHOT>
+Then rebuild various files:
+
+ $ perl pod/buildtoc --build-all
+
+Finally, commit:
+
+ $ git commit -a -m 'add perlXXXdelta'
+
+=item *
Make sure any recent F<pod/perlhist.pod> entries are copied to
F<perlhist.pod> on other branches; typically the RC* and final entries,
=item *
-I<You MUST SKIP this step for SNAPSHOT, RC>
-
-Remind the current maintainer of C<Module::CoreList> to push a new release
-to CPAN.
-
-=item *
-
-I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some much-needed
-rest and relaxation>.
+I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
+much-needed rest and relaxation>.
Thanks for releasing perl!
projects / p5sagit/p5-mst-13.2.git / blobdiff