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
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
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
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.
+
+ $ sh Configure -Dprefix=/tmp/perl-5.x.y -Uinstallusrbinperl \
+ -Duseshrplib -Dd_dosuid
+ $ make
+ $ LD_LIBRARY_PATH=`pwd` make test # or similar for useshrplib
- -Duseshrplib -Dd_dosuid
- make suidperl
+ $ 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 *
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, first edit
+F<ext/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 CPABN modules unreltaed to the modules actually in core.
+Assuming all goes well, it will update
+F<ext/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 ext/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' ext/Module-CoreList/lib/Module/CoreList.pm
=item *
$ make manisort
$ make distclean
$ perl Porting/manicheck
+ $ git status
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 *
$ git push origin ....
-
=item *
Create a tarball. Use the C<-s> option to specify a suitable suffix for
$ 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
=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
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 *
Check that the C<perlbug> utility works. Try the following:
- $ /path/to/perl/perlbug
+ $ bin/perlbug
...
Subject: test bug report
Local perl administrator [yourself]:
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!
+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 *
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 *
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.
+created, for example:
$ 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
Be sure to commit your change:
$ git commit -m 'disarm RCnnn bump' patchlevel.h
+ $ git push origin ....
=item *
I<You MUST SKIP this step for SNAPSHOT, 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 SNAPSHOT, 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/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:
-Run C<perl pod/buildtoc --build-all> to update the following files:
+ -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 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
+
+XXX this previous step needs to fixed to automate it in pod/buildtoc.
+
+Manually update references to the perlNNNdelta version in these files:
-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.)
+ 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>
-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
+
+Edit F<pod.lst> to add an entry for the file, e.g.:
-(see fc5be80860 for an example).
+ perl5101delta Perl changes in version 5.10.1
+
+Then rebuild various files:
+
+ $ perl pod/buildtoc --build-all
+
+Finally, commit:
+
+ $ git commit -a -m 'add perlXXXdelta'
=item *
=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>.
projects / p5sagit/p5-mst-13.2.git / blobdiff