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
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.
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>
$ 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
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'
=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
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 *
$ make perl
If this not the first update for this version, first edit
-F<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.
+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.
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<lib/Module/CoreList.pm>.
+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
+ $ 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 'Update Module::CoreList for 5.x.y' 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:
$ git commit -m 'Update MANIFEST' MANIFEST
=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
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<You MAY SKIP this step for SNAPSHOT>
+I<If you're building a SNAPSHOT, you should STOP HERE>
+
+=item *
Check that the C<perlbug> utility works. Try the following:
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 *
-I<You MAY SKIP this step for SNAPSHOT>
-
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.
=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[] = {
=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/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:
+
+ 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.
-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.)
+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