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
=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
=back
-=head2 Building a release
+=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.
=item *
-Check that files managed by F<regen.pl> and friends are up to date. From
-within your working directory:
-
-
- $ git status
- $ make regen
- $ make regen_perly
- $ git status
-
-If any of the files managed by regen.pl have changed, then you should commit
-the updated versions:
-
- $ git commit -m 'Updated files generated by regen tools for perl 5.x.y' <list of files>
-
-
-=item *
-
I<You MAY SKIP this step for SNAPSHOT>
Get perldelta in a mostly finished state.
I<You MUST SKIP this step for SNAPSHOT>
-Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
+A week or two before the first release candidate, bump the perl version
+number (e.g. from 5.10.0 to 5.10.1), to allow sufficient time for testing
+and smoking with the target version built into the perl executable. For
+subsequent release candidates and the final release, it it not necessary
+to bump the version further.
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
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.
-=item *
-
-Configure and build perl so that you have a Makefile and porting tools:
-
- $ ./Configure -Dusedevel -des
- $ make
+=back
-=item *
+=head2 Building a release - on the day
-Rebuild META.yml:
+This section describes the actions required to make a release (or snapshot
+etc) that are performed on the actual day.
- $ rm META.yml
- $ make META.yml
+=over 4
-Commit META.yml if it has changed:
+=item *
- $ git commit -m 'Updating META.yml in preparation for release of 5.x.y' META.yml
+Review all the items in the previous section,
+L<"Building a release - advance actions"> to ensure they are all done and
+up-to-date.
=item *
-Check that the manifest is sorted and correct:
+I<You MAY SKIP this step for SNAPSHOT>
- $ make manisort
- $ make distclean
- $ perl Porting/manicheck
+Re-read the perldelta to try to find any embarrassing typos and thinkos;
+remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
+with any serious issues for which fixes are not going to happen now; and
+run through pod and spell checkers, e.g.
+ $ podchecker -warnings -warnings pod/perl5101delta.pod
+ $ spell pod/perl5101delta.pod
-Commit MANIFEST if it has changed:
+Also, you may want to generate and view an HTML version of it to check
+formatting, e.g.
- $ git commit -m 'Updating MANIFEST in preparation for release of 5.x.y' MANIFEST
+ $ perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html
+=item *
+
+Make sure you have a gitwise-clean perl directory (no modified files,
+unpushed commits etc):
+ $ git status
=item *
-I<You MUST SKIP this step for SNAPSHOT>
+If not already built, Configure and build perl so that you have a Makefile
+and porting tools:
-A dd an entry to F<pod/perlhist.pod> with the current date:
+ $ ./Configure -Dusedevel -des
+ $ make
- 5.8.9-RC1 2008-Nov-10
+=item *
-Make sure the correct pumpking is listed, 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>.
+Check that files managed by F<regen.pl> and friends are up to date. From
+within your working directory:
-Be sure to commit your changes:
+ $ git status
+ $ make regen
+ $ make regen_perly
+ $ git status
- $ git commit -m 'Updating perlhist in preparation for release of 5.x.y pod/perlhist.pod
+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'
=item *
+Rebuild META.yml:
-I<You MAY SKIP this step for SNAPSHOT>
-
-Re-read the perldelta to try to find any embarrassing typos and thinkos;
-remove any C<TODO> or C<XXX> flags; and run through pod and spell
-checkers, e.g.
-
- podchecker -warnings -warnings pod/perl5101delta.pod
- spell pod/perl5101delta.pod
+ $ rm META.yml
+ $ make META.yml
+ $ git diff
-=item *
+XXX it would be nice to make Porting/makemeta use regen_lib.pl
+to get the same 'update the file if its changed' functionality
+we get with 'make regen' etc.
-I<You MUST SKIP this step for SNAPSHOT>
+Commit META.yml if it has changed:
-Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a
-final release, remove it. [ XXX how now?? see 34813 for old way ]
+ $ git commit -m 'Update META.yml' META.yml
=item *
Update C<Module::Corelist>.
Note that if this is a maint release, you should run the following actions
-from the maint directory, but edit the C<Corelist.pm> in I<blead> and
-subsequently cherry-pick it.
+from the maint directory, but commit the C<Corelist.pm> changes in
+I<blead> and subsequently cherry-pick it.
-corelist.pl uses ftp.funet.fi to verify information about dual-lifed
+F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
modules on CPAN. It can use a full, local CPAN mirror or fall back
to C<wget> or C<curl> to fetch only package metadata remotely.
(If you'd prefer to have a full CPAN mirror, see
http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
+Then change to your perl checkout, and if necessary,
-Then change to your perl checkout.
+ $ make perl
-If you have a local CPAN mirror, run:
+Then, If you have a local CPAN mirror, run:
- $ make perl
$ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
Otherwise, run:
- $ make perl
$ ./perl -Ilib Porting/corelist.pl cpan
This will chug for a while. Assuming all goes well, it will
-update lib/Module/CoreList.pm.
+update F<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
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
Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
entry, as that is likely to reflect the previous version number.
-If this is a final release (rather than a release candidate):
+In addition, if this is a final release (rather than a release candidate):
=over 4
=back
Finally, commit the new version of Module::CoreList:
+(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
+ lib/Module/CoreList.pm
+
+
+=item *
+Check that the manifest is sorted and correct:
+
+ $ make manisort
+ $ make distclean
+ $ perl Porting/manicheck
+
+Commit MANIFEST if it has changed:
+
+ $ git commit -m 'Update MANIFEST' MANIFEST
=item *
-Disarm the patchlevel.h change [ XXX expand ]
+I<You MUST SKIP this step for SNAPSHOT>
+
+Add an entry to F<pod/perlhist.pod> with the current date, e.g.:
+
+ David 5.10.1-RC1 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>.
+
+Be sure to commit your changes:
+
+ $ git commit -m 'add new release to perlhist' pod/perlhist.pod
+
+=item *
+
+I<You MUST SKIP this step for SNAPSHOT>
+
+Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
+a final release, remove it. For example:
+
+ static const char * const local_patches[] = {
+ NULL
+ + ,"RC1"
+ PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
+
+Be sure to commit your change:
+
+ $ git commit -m 'bump version to RCnnn' patchlevel.h
=item *
Build perl, then make sure it passes its own test suite, and installs:
+ $ git clean -xdf
+ $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
+
+ # or if it's an odd-numbered version:
$ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
+
$ make test install
=item *
+Check that the output of C<perl -v> and C<perl -V> are as expected,
+especially as regards version numbers, patch and/or RC levels, and @INC
+paths.
+
+=item *
+
+Push all your recent commits:
+
+ $ git push origin ....
+
+
+=item *
+
Create a tarball. Use the C<-s> option to specify a suitable suffix for
the tarball and directory name:
=item *
+Clean up the temporary directory, e.g.
+
+ $ rm -rf ../perl-x.y.z-RC1
+
+=item *
+
Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
have access to.
Check that the test harness and install work on each test machine:
+ $ make distclean
$ ./Configure -des -Dprefix=/install/path && make all test_harness install
+ $ cd /install/path
=item *
=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'
=item *
-Install Inline.pm
+Try installing a popular CPAN module that's reasonably complex and that
+has dependencies; for example:
- $ ./bin/perl -MCPAN -e'install Inline'
+ CPAN> install Inline
+ CPAN> quit
Check that your perl can run this:
- $ ./bin/perl -lwe 'use Inline C => "int answer() { return 42;} "; print answer'
+ $ ./bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f'
+ 42
+ $
=item *
$ ./bin/cpanp
-
=item *
-Install an XS module.
+Install an XS module, for example:
+
+ CPAN Terminal> i DBI
+ CPAN Terminal> quit
+ $ bin/perl -MDBI -e 1
+
=item *
-If all is well, announce the snapshot to p5p. (For a release candidate,
-instead follow the further steps described later.)
+I<You MAY SKIP this step for SNAPSHOT>
+
+Check that the C<perlbug> utility works. Try the following:
+ $ /path/to/perl/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
+try it again, this time actually submitting the bug report. Check that it
+shows up, then remember to close it!
=item *
If anything goes wrong after this point, you will need to re-prepare
a new release with a new minor version or RC number.
-You may wish to create a .bz2 version of the tarball and upload that too.
+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 revsion you built the release from:
+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.
- $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
+ $ 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
=item *
+I<You MUST SKIP this step for SNAPSHOT>
+
+Disarm the F<patchlevel.h> change; for example,
+
+ static const char * const local_patches[] = {
+ NULL
+ - ,"RC1"
+ PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
+
+Be sure to commit your change:
+
+ $ git commit -m 'disarm RCnnn bump' patchlevel.h
+
+
+=item *
+
Mail p5p to announce your new release, with a quote you prepared earlier.
=item *
=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>
-Ask Jarkko to update http://www.cpan.org/src/README.html and
-Rafael to update http://dev.perl.org/perl5/
+Ask Jarkko to update the descriptions of which tarballs are current in
+http://www.cpan.org/src/README.html, and Rafael to update
+http://dev.perl.org/perl5/
=item *
If this was a maint release, then edit F<Porting/mergelog> to change
all the C<d> (deferred) flags to C<.> (needs review).
-XXX - we should be able to use git to automate much of the role
-previously filled by the mergelog.
-
=item *
I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD>
projects / p5sagit/p5-mst-13.2.git / blobdiff