+=encoding utf8
=head1 NAME
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
This document describes the series of tasks required - some automatic, some
manual - to produce a perl release of some description, be that a snaphot,
-release candidate, or final release.
+release candidate, or final, numbered release of maint or blead.
-The release process is primarily executed by the current pumpking.
+The release process has traditionally been executed by the current
+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 pumpking and is
-a base for ideas on how the various tasks could be automated or
-distributed.
+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 outline of a typical release cycle is as follows:
perl-5.10.2 is released
post-release actions are performed, including creating new
- perl5103delta.pod
+ perldelta.pod
... the cycle continues ...
=head1 DETAILS
+Some of the tasks described below apply to all four types of
+release of Perl. (snapshot, 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
+type of release, you will see a notation to that effect at
+the beginning of the step.
+
+=head2 Release types
+
+=over 4
+
+=item Snapshot
+
+A snapshot is intended to encourage in-depth testing from time-to-time,
+for example after a key point in the stabilisation of a branch. It
+requires fewer steps than a full release, and the version number of perl in
+the tarball will usually be the same as that of the previous release.
+
+=item Release Candidate (RC)
+
+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
+
+At this point you should have a working release candidate with few or no
+changes since.
+
+It's essentially the same procedure as for making a release candidate, but
+with a whole bunch of extra post-release steps.
+
+=item Blead release
+
+It's essentially the same procedure as for making a release candidate, but
+with a whole bunch of extra post-release steps.
+
+=back
=head2 Prerequisites
=over 4
-=item *
+=item PAUSE account
+
+I<SKIP this step for SNAPSHOT>
Make sure you have a PAUSE account suitable for uploading a perl release.
If you don't have a PAUSE account, then request one:
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
+KE<0xf6>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 *
+=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.
+Work to fall back to using a remote mirror via HTTP is incomplete
+but ongoing. (No, a minicpan mirror is not sufficient)
+
+=item git checkout and commit bit
You will need a working C<git> installation, checkout of the perl
git repository and perl commit bit. For information about working
-with perl and git, see F<pod/perlrepository.pod>.
+with perl and git, see F<pod/perlgit.pod>.
If you are not yet a perl committer, you won't be able to make a
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.
-=back
+=item Quotation for release announcement epigraph
-=head2 Building a snapshot
+I<SKIP this step for SNAPSHOT and RC>
-A snapshot is intended to encourage in-depth testing from time-to-time,
-for example after a key point in the stabilisation of a branch. It
-requires fewer steps than a full release, and the version number of perl in
-the tarball will usually be the same as that of the previous release.
+For a numbered blead or maint release of perl, you will need a quotation
+to use as an epigraph to your release announcement. (There's no harm
+in having one for a snapshot, but it's not required).
-=over 4
-=item *
+=back
-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.
-=item *
+=head2 Building a release - advance actions
-Configure and build perl so that you have a Makefile and porting tools:
+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<must> be
+done in the run up to a release.
- $ ./Configure -Dusedevel -des
- $ make
+=over 4
=item *
-Rebuild META.yml:
+I<You MAY SKIP this step for SNAPSHOT>
- $ rm META.yml
- $ make META.yml
+Ensure that dual-life CPAN modules are synchronised with CPAN. Basically,
+run the following:
-Commit META.yml if it has changed:
+ $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
- $ git commit -m 'Updating META.yml in preparation for release of 5.x.y' META.yml
+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.
-=item *
+To see which core distro versions differ from the current CPAN versions:
-Check that the manifest is sorted and correct:
+ $ ./perl -Ilib Porting/core-cpan-diff -x -a
- $ make manisort
- $ make distclean
- $ perl Porting/manicheck
+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
+have some extra changes.
+=item *
-Commit MANIFEST if it has changed:
+I<You MAY SKIP this step for SNAPSHOT>
- $ git commit -m 'Updating MANIFEST in preparation for release of 5.x.y' MANIFEST
+Ensure dual-life CPAN modules are stable, which comes down to:
+ for each module that fails its regression tests on $current
+ did it fail identically on $previous?
+ if yes, "SEP" (Somebody Else's Problem)
+ else work out why it failed (a bisect is useful for this)
+ attempt to group failure causes
+
+ for each failure cause
+ is that a regression?
+ if yes, figure out how to fix it
+ (more code? revert the code that broke it)
+ else
+ (presumably) it's relying on something un-or-under-documented
+ should the existing behaviour stay?
+ yes - goto "regression"
+ no - note it in perldelta as a significant bugfix
+ (also, try to inform the module's author)
=item *
-If this is a release candidate or final release, add an entry to
-F<pod/perlhist.pod> with the current date, e.g.
+I<You MAY SKIP this step for SNAPSHOT>
- 5.8.9-RC1 2008-Nov-10
+Similarly, monitor the smoking of core tests, and try to fix. See
+L<http://doc.procura.nl/smoke/index.html> for a summary. See also
+L<http://www.nntp.perl.org/group/perl.daily-build.reports/> which has
+the raw reports.
+
+=item *
-Make sure the correct pumpking is listed, and if this is your first time,
-append your name to C<THE KEEPERS OF THE PUMPKIN>.
+I<You MAY SKIP this step for SNAPSHOT>
+
+Similarly, monitor the smoking of perl for compiler warnings, and try to
+fix.
=item *
-Build perl, then make sure it passes its own test suite, and installs:
+I<You MAY SKIP this step for SNAPSHOT>
- $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
- $ make test install
+Get perldelta in a mostly finished state.
+
+Read F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
+every section it lists is, if necessary, populated and complete. Copy
+edit the whole document.
=item *
-Create a tarball. Use the C<-s> option to specify a suitable suffix for
-the tarball and directory name:
+I<You MUST SKIP this step for SNAPSHOT>
- $ cd root/of/perl/tree
- $ make distclean
- $ git clean -xdf # make sure perl and git agree on files
+Bump the version number (e.g. from 5.12.0 to 5.12.1).
- $ perl Porting/makerel -b -s `git describe` # for a snapshot
- $ perl Porting/makerel -b -s RC1 # for a release candidate
- $ perl Porting/makerel -b # for a final release
+For a blead release, this can happen on the day of the release. For a
+release candidate for a stable perl, this should happen a week or two
+before the first release candidate 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.
-This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
-the MANIFEST files into it, sets the correct permissions on them,
-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.
+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 directory looking for likely candidates. The command line
+arguments are the old and new version numbers, and -s means scan:
-XXX if we go for extra tags and branches stuff, then add the extra details
-here
+ $ ./perl -Ilib Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
-=item *
+This produces a file containing a list of suggested edits, e.g.:
-Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
-have access to.
+ NetWare/Makefile
-=item *
+ 89: -MODULE_DESC = "Perl 5.10.0 for NetWare"
+ +MODULE_DESC = "Perl 5.10.1 for NetWare"
-Download the tarball to some other machine. For a release candidate,
-you really want to test your tarball on two or more different platforms
-and architectures. The #p5p IRC channel on irc.perl.org is a good place
-to find willing victims.
+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. 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:
-=item *
+ $ ./perl -Ilib Porting/bump-perl-version -u < /tmp/scan
-Check that basic configuration and tests work on each test machine:
+which will update all the files shown.
- $ ./Configure -des && make all test
+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 unchanged.
+The line in F<INSTALL> about "is binary incompatible with" requires a
+correct choice of earlier version to declare incompatibility with.
-=item *
+Also note that this tool
+currently only detects a single substitution per line: so in particular,
+this line in README.vms needs special handling:
-Check that the test harness and install work on each test machine:
+ rename perl-5^.10^.1.dir perl-5_10_1.dir
- $ ./Configure -des -Dprefix=/install/path && make all test_harness install
+When doing a blead release, also make sure the C<PERL_API_*> constants in
+F<patchlevel.h> are in sync with the version you're releasing, unless you're
+absolutely sure the release you're about to make is 100% binary compatible
+to an earlier release. When releasing a stable perl version, the C<PERL_API_*>
+constants C<MUST NOT> be changed as we aim to guarantee binary compatibility
+in maint branches.
-=item *
+Commit your changes:
-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.
+ $ git st
+ $ git diff
+ B<review the delta carefully>
-Note that the results may be different without a F<.git/> directory,
-which is why you should test from the tarball.
+ $ 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 *
-Bootstrap the CPAN client on the clean install:
+I<You MUST SKIP this step for SNAPSHOT>
+
+Review and update INSTALL to account for the change in version number;
+in particular, the "Coexistence with earlier versions of perl 5" section.
- $ ./bin/perl -MCPAN -e'shell'
+Be particularly careful with the section "Upgrading from 5.X.Y or earlier". For
+stable releases, this needs to refer to the last release in the previous
+development cycle. For blead releases, it needs to refer to the previous blead
+release.
=item *
-Install Inline.pm
+I<You MUST SKIP this step for SNAPSHOT>
- $ ./bin/perl -MCPAN -e'install Inline'
+Update the F<Changes> file to contain the git log command which would show
+all the changes in this release. You will need assume the existence of a
+not-yet created tag for the forthcoming release; e.g.
-Check that your perl can run this:
+ git log ... perl-5.10.0..perl-5.12.0
- $ ./bin/perl -lwe 'use Inline C => "int answer() { return 42;} "; print answer'
+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 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 *
-Bootstrap the CPANPLUS client on the clean install:
+Check some more build configurations. The check that setuid builds and
+installs is for < 5.11.0 only.
- $ ./bin/cpanp
+ $ 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
-=item *
+(Then delete the installation directory.)
-Install an XS module.
+XXX think of other configurations that need testing.
=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>
+
+L<perlport> has a section currently named I<Supported Platforms> that
+indicates which platforms are known to build in the current release.
+If necessary update the list and the indicated version number.
=back
-=head2 Actions prior to the first release candidate
+=head2 Building a release - on the day
-A week or two before the first release candidate, there are some additional
-tasks you should perform (actually, some of these should be done regularly
-anyway, but they definitely need doing now):
+This section describes the actions required to make a release (or snapshot
+etc) that are performed on the actual day.
=over 4
=item *
-Check F<Maintainers.pl> for consistency; both these commands should
-produce no output:
+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 *
- $ perl Porting/Maintainers --checkmani
- $ perl Porting/Maintainers --checkmani lib/ ext/
+For a blead release, if you did not bump the perl version number as part
+of I<advance actions>, do that now.
=item *
-Ensure that dual-life CPAN modules are synchronised with CPAN. Basically,
-run the following:
+I<You MAY SKIP this step for SNAPSHOT>
- $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
+Finalize the perldelta. In particular, fill in the Acknowledgements
+section. You can generate a list of contributors with checkAUTHORS.pl.
+For example:
-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.
+ $ git log --pretty=fuller v5.13.2..HEAD | \
+ perl Porting/checkAUTHORS.pl --who -
-To see which core distro versions differ from the current CPAN versions:
+Look at the previous L<perldelta> for how to write the opening
+paragraph of the Acknowledgements section. To get the amount of
+changed files and number of lines use this command:
- $ ./perl -Ilib Porting/core-cpan-diff -x -a
+ $ git diff --shortstat v5.13.8..v5.13.9 | \
+ ./perl -Ilib -nE 'my ($files, $insert, $delete) = /(\d+)/ga; say "$files files and ", $insert + $delete, " lines changed"'
-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
-have some extra changes.
+Making sure to round off the number of lines changed.
-=item *
+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.
-Ensure dual-life CPAN modules are stable, which comes down to:
+ $ podchecker -warnings -warnings pod/perldelta.pod
+ $ spell pod/perldelta.pod
- for each module that fails its regression tests on $current
- did it fail identically on $previous?
- if yes, "SEP" (Somebody Else's Problem)
- else work out why it failed (a bisect is useful for this)
+Also, you may want to generate and view an HTML version of it to check
+formatting, e.g.
- attempt to group failure causes
+ $ ./perl -Ilib ext/Pod-Html/pod2html pod/perldelta.pod > /tmp/perldelta.html
- for each failure cause
- is that a regression?
- if yes, figure out how to fix it
- (more code? revert the code that broke it)
- else
- (presumably) it's relying on something un-or-under-documented
- should the existing behaviour stay?
- yes - goto "regression"
- no - note it in perldelta as a significant bugfix
- (also, try to inform the module's author)
+Another good HTML preview option is http://search.cpan.org/pod2html
+
+If you make changes, be sure to commit them.
=item *
-Similarly, monitor the smoking of core tests, and try to fix.
+Make sure you have a gitwise-clean perl directory (no modified files,
+unpushed commits etc):
+
+ $ git status
+ $ git clean -dxf
=item *
-Similarly, monitor the smoking of perl for compiler warnings, and try to
-fix.
+If not already built, Configure and build perl so that you have a Makefile
+and porting tools:
+
+ $ ./Configure -Dusedevel -des && make
=item *
-Run F<Porting/cmpVERSION.pl> to compare the current source tree with the
-previous version to check for for modules that have identical version
-numbers but different contents, e.g.:
+I<You MUST SKIP this step for SNAPSHOT>
- $ cd ~/some-perl-root
- $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 .
+Update C<Module::CoreList> with module version data for the new release.
-then bump the version numbers of any non-dual-life modules that have
-changed since the previous release, but which still have the old version
-number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x),
-then compare against both.
+Note that if this is a maint release, you should run the following actions
+from the maint branch, but commit the C<CoreList.pm> changes in
+I<blead> and subsequently cherry-pick it. XXX need a better example
-Note that some of the files listed may be generated (e.g. copied from ext/
-to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm);
-make sure you edit the correct file!
+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're
+on Win32, then installing Cygwin is one way to have commands like C<wget>
+and C<curl> available.)
+
+(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,
+
+ $ make
+
+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
+
+Otherwise, run:
-Once all version numbers have been bumped, re-run the checks.
+ $ ./perl -Ilib Porting/corelist.pl cpan
-Then run again without the -x option, to check that dual-life modules are
-also sensible.
+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 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
+appear in the final release, and leave as-is for the later RCs and final).
+
+Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
+entry, as that is likely to reflect the previous version number.
+
+Also edit Module::CoreList's new version number in its F<Changes>
+file.
+
+You should also add the version you're about to release to the
+L<Module::CoreList/CAVEATS> section which enumerates the perl releases
+that Module::CoreList covers.
+
+In addition, if this is a final release (rather than a release candidate):
+
+=over 4
=item *
-Check that files managed by F<regen.pl> and friends are up to date. From
-within your working directory:
+Update this version's entry in the C<%released> hash with today's date.
+=item *
- $ git status
- $ make regen
- $ make regen_perly
- $ git status
+Make sure that the script has correctly updated the C<CAVEATS> section
-If any of the files managed by regen.pl have changed, then you should commit
-the updated versions:
+=back
- $ git commit -m 'Updated files generated by regen tools for perl 5.x.y' <list of files>
+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 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm
=item *
-Get perldelta in a mostly finished state.
+Check that the manifest is sorted and correct:
-Peruse F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
-every section it lists is, if necessary, populated and complete. Copy
-edit the whole document.
+ $ make distclean
+ $ git clean -xdf # This shouldn't be necessary if distclean is correct
+ $ perl Porting/manicheck
+
+If manicheck turns up anything wrong, update MANIFEST and begin this step again.
+
+ $ ./configure -des -Dusedevel
+ $ make test_porting
+ $ git commit -m 'Update MANIFEST' MANIFEST
=item *
-Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
+I<You MUST 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:
+Add an entry to F<pod/perlhist.pod> with the current date, e.g.:
- $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
+ David 5.10.1-RC1 2009-Aug-06
-This produces a file containing a list of suggested edits, eg:
+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>.
- NetWare/Makefile
+Be sure to commit your changes:
- 89: -MODULE_DESC = "Perl 5.10.0 for NetWare"
- +MODULE_DESC = "Perl 5.10.1 for NetWare"
+ $ git commit -m 'add new release to perlhist' pod/perlhist.pod
-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:
+=item *
- $ Porting/bump-perl-version -u < /tmp/scan
+I<You MUST SKIP this step for SNAPSHOT or BLEAD release>
-which will update all the files shown; then commit the changes.
+Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
+a final release, remove it. For example:
-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:
+ static const char * const local_patches[] = {
+ NULL
+ + ,"RC1"
+ PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
- rename perl-5^.10^.1.dir perl-5_10_1.dir
+Be sure to commit your change:
+ $ git commit -m 'bump version to RCnnn' patchlevel.h
=item *
-Review and update INSTALL to account for the change in version number;
-in particular, the "Coexistence with earlier versions of perl 5" section.
+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 *
-Update the F<Changes> file to contain the git log command which would show
-all the changes in this release. You will need assume the existence of a
-not-yet created tag for the forthcoming release; e.g.
+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. Note that as they have been been built from a git working
+directory, they will still identify themselves using git tags and
+commits.
- git log ... perl-5.10.0..perl5.12.0
+Then delete the temporary installation.
-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.
+=item *
+
+Push all your recent commits:
+
+ $ git push origin ....
=item *
-Check some more build configurations, e.g.
+I<You MUST SKIP this step for SNAPSHOT>
- -Duseshrplib -Dd_dosuid
- make suidperl
+Tag the release (e.g.):
-Check that setuid installs works (for < 5.11.0 only).
-XXX any other configs?
+ $ git tag v5.11.0 -m'First release of the v5.11 series!'
+(Adjust the syntax appropriately if you're working on Win32, i.e. use
+C<-m "..."> rather than C<-m'...'>.)
+
+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 *
-Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if
-necessary, update the script to include new alias mappings.
+Create a tarball. Use the C<-s> option to specify a suitable suffix for
+the tarball and directory name:
-XXX This script is currently broken (7/2009). It needs updating to work
-with git and a lack of Changes files.
+ $ cd root/of/perl/tree
+ $ make distclean
+ $ git clean -xdf # make sure perl and git agree on files
+ $ git status # and there's nothing lying around
-=back
+ $ perl Porting/makerel -b -s `git describe` # for a snapshot
+ $ perl Porting/makerel -b -s RC1 # for a release candidate
+ $ perl Porting/makerel -b # for a final release
+
+This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
+the MANIFEST files into it, sets the correct permissions on them,
+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.
-=head2 Building a release candidate
+If you're getting your tarball suffixed with -uncommitted and you're sure
+your changes were all committed, you can override the suffix with:
-(At this point you should already have performed the actions described in
-L</"Actions prior to the first release candidate">.) You should review
-that section to ensure that everything there has done, and to see whether
-any of those actions (such as consistency checks) need to be repeated.
+ $ perl Porting/makerel -b -s ''
-=over 4
+XXX if we go for extra tags and branches stuff, then add the extra details
+here
=item *
-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.
+Clean up the temporary directory, e.g.
- podchecker -warnings -warnings pod/perl5101delta.pod
- spell pod/perl5101delta.pod
+ $ rm -rf ../perl-x.y.z-RC1
=item *
-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 ]
+Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
+have access to.
=item *
-Update C<Module::Corelist>.
+Download the tarball to some other machine. For a release candidate,
+you really want to test your tarball on two or more different platforms
+and architectures. The #p5p IRC channel on irc.perl.org is a good place
+to find willing victims.
-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.
+=item *
-corelist.pl uses ftp.funet.fi to verify information about dual-lifed
-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.
+Check that basic configuration and tests work on each test machine:
-(If you'd prefer to have a full CPAN mirror, see
-http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
+ $ ./Configure -des && make all test
+=item *
-Then change to your perl checkout.
+Check that the test harness and install work on each test machine:
-If you have a local CPAN mirror, run:
+ $ make distclean
+ $ ./Configure -des -Dprefix=/install/path && make all test_harness install
+ $ cd /install/path
- $ perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
+=item *
-Otherwise, run:
+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.
+
+Note that the results may be different without a F<.git/> directory,
+which is why you should test from the tarball.
- $ perl -Ilib Porting/corelist.pl cpan
+=item *
-This will chug for a while. Assuming all goes well, it will
- update lib/Module/CoreList.pm.
+Run the Installation Verification Procedure utility:
-Check that file over carefully:
+ $ ./perl utils/perlivp
+ ...
+ All tests successful.
+ $
- $ git diff lib/Module/CoreList.pm
+=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:
-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
-appear in the final release, and leave as-is for the later RCs and final).
+ 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]
-Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
-entry, as that is likely to reflect the previous version number.
+=item *
+Bootstrap the CPAN client on the clean install:
+ $ bin/perl -MCPAN -e "shell"
+If you're running this on Win32 you probably also need a set of Unix
+command-line tools available for CPAN to function correctly without
+Perl alternatives like LWP installed. Cygwin is an obvious choice.)
-Add or update an entry to the C<%released> hash, including today's date
-(if this is just a release candidate, set the date to '????-??-??').
+=item *
-Finally, commit the new version of Module::CoreList:
+Try installing a popular CPAN module that's reasonably complex and that
+has dependencies; for example:
- $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \
- lib/Module/Corelist.pm
+ CPAN> install Inline
+ CPAN> quit
+Check that your perl can run this:
+
+ $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
+ 42
+ $
+
+=item *
+
+Bootstrap the CPANPLUS client on the clean install:
+
+ $ bin/cpanp
+
+(Again, on Win32 you'll need something like Cygwin installed, but make sure
+that you don't end up with its various F<bin/cpan*> programs being found on
+the PATH before those of the Perl that you're trying to test.)
+
+=item *
+
+Install an XS module, for example:
+
+ CPAN Terminal> i DBI
+ CPAN Terminal> quit
+ $ bin/perl -MDBI -e 1
+ $
=item *
-Follow the instructions in the section L</"Building a snapshot">, then
-carry on with the extra steps that follow here.
+I<If you're building a SNAPSHOT, you should STOP HERE>
=item *
-Disarm the patchlevel.h change [ XXX expand ]
+Check that the L<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 *
Then check that the smoke tests pass (particularly on Win32). If not, go
back and fix things.
+Note that for I<BLEAD> releases this may not be practical. It takes a
+long time for the smokers to catch up, especially the Win32
+smokers. This is why we have a RC cycle for I<MAINT> releases, but for
+I<BLEAD> releases sometimes the best you can do is to plead with
+people on IRC to test stuff on their platforms, fire away, and then
+hope for the best.
=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.
+ https://pause.perl.org/
-=item *
+(Login, then select 'Upload a file to CPAN')
-Create a tag for the exact git revsion you built the release from:
+If your workstation is not connected to a high-bandwidth,
+high-reliability connection to the Internet, you should probably use the
+"GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the
+new release from wherever you put it for testers to find it. This will
+eliminate anxious gnashing of teeth while you wait to see if your
+15 megabyte HTTP upload successfully completes across your slow, twitchy
+cable modem. You can make use of your home directory on dromedary for
+this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
+F</home/USERNAME/public_html>, where F<USERNAME> is your login account
+on dromedary. I<Remember>: if your upload is partially successful, you
+may need to contact a PAUSE administrator or even bump the version of perl.
- $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
- $ git push origin tag perl-5.10.1-RC1
+Upload both the .gz and .bz2 versions of the tarball.
+
+Wait until you receive notification emails from the PAUSE indexer
+confirming that your uploads have been received. IMPORTANT -- you will
+probably get an email that indexing has failed, due to module permissions.
+This is considered normal.
+
+Do not proceed any further until you are sure that your tarballs are on
+CPAN. Check your authors directory on one of the "fast" CPAN mirrors
+(e.g., cpan.hexten.net
+or cpan.cpantesters.org) to confirm that your uploads have been successful.
=item *
-Mail p5p to announce your new release, with a quote you prepared earlier.
+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 (e.g.):
+
+ $ git push origin tag v5.11.0
=item *
-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.)
+I<You MUST SKIP this step for SNAPSHOT or BLEAD release>
-=back
+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 */
-=head2 Making a final release
+Be sure to commit your change:
-At this point you should have a working release candidate with few or no
-changes since.
+ $ git commit -m 'disarm RCnnn bump' patchlevel.h
+ $ git push origin ....
-It's essentially the same procedure as for making a release candidate, but
-with a whole bunch of extra post-release steps.
-=over 4
+=item *
+
+Mail p5p to announce your new release, with a quote you prepared earlier.
=item *
-Follow the same steps as for making a release candidate, then
+Add your quote to F<Porting/epigraphs.pod> and commit it.
=item *
-Ask Jarkko to update http://www.cpan.org/src/README.html and
-Rafael to update http://dev.perl.org/perl5/
+I<You MUST SKIP this step for RC>
+
+Remind the current maintainer of C<Module::CoreList> to push a new release
+to CPAN.
=item *
-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. ]
+I<You MUST SKIP this step for RC>
-In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
-entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
-following files:
+Create a new perldelta.
- MANIFEST
- pod/perl.pod
- win32/pod.mak
- vms/descrip_mms.template
+First, update the F<.gitignore> file in the F<pod/> folder to ignore the next
+release's generated F<pod/perlNNNdelta.pod> file rather than this releases's
+one which we are about to set in stone (where NNN is the perl version number
+without the dots. i.e. 5135 for 5.13.5).
-(F<vms/descrip_mms.template> still needs a manual edit to bump the
-C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
+Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>.
-and change perlNNNdelta references to the new version in these files
+Now edit the moved delta file to change the C<NAME> from C<perldelta> to
+C<perlNNNdelta>.
- INSTALL
- win32/Makefile.mk
- win32/Makefile
- Makefile.SH
- README
+Then create a new empty perldelta.pod file for the new release; see
+F<Porting/how_to_write_a_perldelta.pod>.
-Also, edit the previous delta file to change the C<NAME> from C<perldelta>
-to C<perlNNNdelta>.
+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.
-These two lists of files probably aren't exhaustive; do a recursive grep
-on the previous filename to look for suitable candidates.
+Then commit the move and the new file.
-(see 16410843ea for an example).
+For example, assuming you just released 5.10.1:
-=item *
+ $ git mv pod/perldelta.pod pod/perl5101delta.pod
+ $ (edit pod/perl5101delta.pod to retitle)
+ $ git add pod/perl5101delta.pod
-If this was a maintenance release, then edit F<Porting/mergelog> to change
-all the C<d> (deferred) flags to C<.> (needs review).
+ $ cp -i Porting/perldelta_template.pod pod/perldelta.pod
+ $ (edit pod/perldelta.pod)
+ $ git add pod/perldelta.pod
+ $ git commit -m 'create perldelta for 5.10.2'
+Now you need to update various tables of contents, most of which can be
+generated automatically.
-=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
-If this was a major release, then
+Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
+the following files:
-=over
+ MANIFEST
+ Makefile.SH
+ pod.lst
+ pod/perl.pod
+ vms/descrip_mms.template
+ win32/Makefile
+ win32/makefile.mk
+ win32/pod.mak
+
+Finally, commit:
+
+ $ git commit -a -m 'update TOC for perlNNNdelta'
+
+At this point you may want to compare the commit with a previous bump to
+see if they look similar. See commit 2b6e134265 for an example of a
+previous version bump.
=item *
-bump the version, e.g. 5.12.0 to 5.13.0;
+I<You MUST SKIP this step for RC, BLEAD>
-=item *
+If this was the first release of a new maint series, (5.x.0 where x is
+even), then create a new maint branch based on the commit tagged as
+the current release and bump the version in the blead branch in git,
+e.g. 5.12.0 to 5.13.0.
[ XXX probably lots more stuff to do, including perldelta,
C<lib/feature.pm> ]
+Assuming you're using git 1.7.x or newer:
+
+ $ git checkout -b maint-5.12
+ $ git push origin -u maint-5.12
+
=item *
-Create a new maint branch with an empty Porting/mergelog file
-[ XXX and lots of other stuff too, probably ]
+I<You MUST SKIP this step for RC, BLEAD>
-=back
+Copy the perldelta.pod for this release into the other branches; for
+example:
-=item *
+ $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
+ $ git add pod/perl5101delta.pod
-Copy the perlNNNdelta.pod for this release into the other branches, and
-remember to update these files on those branches too:
+Edit F<pod.lst> to add an entry for the file, e.g.:
- MANIFEST
- pod.lst
- pod/perl.pod
- vms/descrip_mms.template
- win32/pod.mak
+ perl5101delta Perl changes in version 5.10.1
-(see fc5be80860 for an example).
+Then rebuild various files:
+
+ $ perl pod/buildtoc --build-all
+
+Finally, commit:
+
+ $ git commit -a -m 'add perlXXXdelta'
=item *
=item *
-Remind the current maintainer of C<Module::CoreList> to push a new release
-to CPAN.
+If necessary, send an email to C<perlbug-admin at perl.org> requesting
+that new version numbers be added to the RT fields C<Perl Version> and
+C<Fixed In>.
+
+=item *
+
+I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
+much-needed rest and relaxation>.
+
+Thanks for releasing perl!
+
+=back
+
+=head2 Building a release - the day after
+
+=over 4
+
+=item *
+
+Check your author directory under L<http://www.cpan.org/authors/id/>
+to ensure that the tarballs are available on the website.
+
+=item *
+
+Check C</src> on CPAN (on a fast mirror) to ensure that links to
+the new tarballs have appeared. There should be links in C</src/5.0>
+(which is accumulating all new versions), links in C</src> (which shows
+only the latest version on each branch), and an appropriate mention in
+C</src/README.html> (which describes the latest versions).
+
+These links should appear automatically, some hours after upload.
+If they don't, or the C<README.html> description is inadequate,
+ask Ask <ask@perl.org>.
+
+=item *
+
+Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
+have been correctly mirrored to the website.
+If they haven't, ask Ask <ask@perl.org>.
+
+=item *
+
+Check L<http://search.cpan.org> to see if it has indexed the distribution.
+It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>.
+
+=item *
+
+I<This step ONLY for STABLE>
+
+Ask Rafael to update L<http://dev.perl.org/perl5/>.
=back
https://perl5.git.perl.org / perl5.git / blobdiff