a few weeks before the release, a number of steps are performed,
including bumping the version to 5.10.2
- ...a few weeks passes...
+ ...a few weeks pass...
perl-5.10.2-RC1 is released
sweet-talking somebody with a Github account into obedience is needed. This
is only needed on the day of the release or shortly afterwards.
-=for checklist skip RC
-
=head3 Quotation for release announcement epigraph
-I<SKIP this step for RC>
-
-For all except an RC release of perl, you will need a quotation
-to use as an epigraph to your release announcement.
+You will need a quotation to use as an epigraph to your release announcement.
=head2 Building a release - advance actions
$ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
-Passing C<-u cpan> (and maybe C<-u undef>) will probably be helpful, since
-it limits the search to distributions with those upstream sources. (It's
-OK for blead upstream to differ from CPAN because those dual-life releases
-usually come I<after> perl is released.
+Passing C<-u cpan> will probably be helpful, since it limits the search to
+distributions with 'cpan' upstream source. (It's OK for blead upstream to
+differ from CPAN because those dual-life releases usually come I<after> perl
+is released.)
See also the C<-d> and C<-v> options for more detail (and the C<-u> option as
mentioned above). You'll probably want to use the C<-c cachedir> option to
but can provide a good first pass to quickly get a list of modules which
definitely haven't changed, to avoid having to download absolutely everything.
-For a BLEAD release with 'cpan' upstream, if a CPAN release appears to be ahead
-of blead, then consider updating it (or asking the relevant porter to do so).
-If blead contains edits to a 'cpan' upstream module, this is naughty but
-sometimes unavoidable to keep blead tests passing. Make sure the affected file
-has a CUSTOMIZED entry in F<Porting/Maintainers.pl>. For 'undef' upstream,
-you'll have to use your judgment for whether any delta should be ignored (like
-'blead' upstream) or treated like a 'cpan' upstream and flagged. Ask around on
-#p5p if you're not sure.
+For a BLEAD-POINT or BLEAD-FINAL release with 'cpan' upstream, if a CPAN
+release appears to be ahead of blead, then consider updating it (or asking the
+relevant porter to do so). (However, if this is a BLEAD-FINAL release or one of
+the last BLEAD-POINT releases before it and hence blead is in some kind of
+"code freeze" state (e.g. the sequence might be "contentious changes freeze",
+then "user-visible changes freeze" and finally "full code freeze") then any
+CPAN module updates must be subject to the same restrictions, so it may not be
+possible to update all modules until after the BLEAD-FINAL release.) If blead
+contains edits to a 'cpan' upstream module, this is naughty but sometimes
+unavoidable to keep blead tests passing. Make sure the affected file has a
+CUSTOMIZED entry in F<Porting/Maintainers.pl>.
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
=item *
Remove files we do not need. That is, remove any files that match the
-entries in C<@IGNORE> in F<Porting/Maintainer.pl>, and anything that
+entries in C<@IGNOR
ABLE> in F<Porting/Maintainer.pl>, and anything that
matches the C<EXCLUDED> section of the distro's entry in the C<%Modules>
hash.
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)
+ 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
+ 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)
+ 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)
=head3 monitor smoke tests for failures
The line in F<INSTALL> about "is binary incompatible with" requires a
correct choice of earlier version to declare incompatibility with.
+For the first RC release leading up to a BLEAD-FINAL release, update the
+description of which releases are now "officially" supported in
+F<pod/perlpolicy.pod>.
+
When doing a BLEAD-POINT or BLEAD-FINAL 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 MAINT perl version, the C<PERL_API_*>
-constants C<MUST NOT> be changed as we aim to guarantee binary compatibility
-in maint branches.
+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 MAINT
+perl version, the C<PERL_API_*> constants C<MUST NOT> be changed as we aim
+to guarantee binary compatibility in maint branches.
After editing, regenerate uconfig.h (this must be run on a system with a
/bin/sh available):
- $ perl regen/uconfig_h.pl
+ $ perl regen/uconfig_h.pl
This might not cause any new changes.
+You may also need to regen opcodes:
+
+ $ ./perl -Ilib regen/opcode.pl
+
+You may have to add stub entries in C<%Module::CoreList::version>,
+C<%Module::CoreList::deprecated> and C<%Module::CoreList::Utils::delta>.
+If so, you must up their version numbers as well.
+
Test your changes:
- $ git clean -xdf # careful if you don't have local files to keep!
- $ ./Configure -des -Dusedevel
- $ make
- $ make test
+ $ git clean -xdf # careful if you don't have local files to keep!
+ $ ./Configure -des -Dusedevel
+ $ make
+ $ make test
Commit your changes:
- $ git status
- $ git diff
- B<review the delta carefully>
+ $ git status
+ $ git diff
+ B<review the delta carefully>
- $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
+ $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
At this point you may want to compare the commit with a previous bump to
-see if they look similar. See commit 0e79a3d1bc for an example of a
+see if they look similar. See commit f7cf42bb69 for an example of a
previous version bump.
When the version number is bumped, you should also update Module::CoreList
For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT
release (so for 5.15.3 this would be 5.15.2).
+=head3 Check copyright years
+
+Check that the copyright years are up to date by running:
+
+ $ ./perl t/porting/copyright.t --now
+
+Remedy any test failures by editing README or perl.c accordingly (search for
+the "Copyright"). If updating perl.c, check if the file's own copyright date in
+the C comment at the top needs updating, as well as the one printed by C<-v>.
+
=head3 Check more build configurations
Try running the full test suite against multiple Perl configurations. Here are
=head3 update Module::CoreList
-Update C<Module::CoreList> with module version data for the new release.
+=head4 Bump Module::CoreList* $VERSIONs
+
+If necessary, bump C<$Module::CoreList::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).
+It may also happen that C<Module::CoreList> has been modified in blead, and
+hence has a new version number already. (But make sure it is not the same
+number as a CPAN release.)
+
+C<$Module::CoreList::TieHashDelta::VERSION> and
+C<$Module::CoreList::Utils::VERSION> should always be equal to
+C<$Module::CoreList::VERSION>. If necessary, bump those two versions to match
+before proceeding.
+
+The files to modify are: F<dist/Module-CoreList/lib/Module/CoreList.pm>,
+F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> and
+F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm>.
+
+=head4 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 branch, but commit the C<CoreList.pm> changes in
DAPM May 2013 ]
-
F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
modules on CPAN. It can use a full, local CPAN mirror and/or fall back
on HTTP::Tiny to fetch package metadata remotely.
$ make
-Before updating Module::CoreList, first edit
-F<dist/Module-CoreList/lib/Module/CoreList.pm> and delete any 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
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>.
+F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly
+F<dist/Module-CoreList/lib/Module/CoreList.pod> and/or
+F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
-Check that file over carefully:
+Check those files over carefully:
$ git diff dist/Module-CoreList/lib/Module/CoreList.pm
-
-XXX I'm not sure if this updates Module::CoreList::Utils, so double
-check that file carefully.
-
-=head4 Bump C<$Module::CoreList::VERSION>
-
-If necessary, bump C<$Module::CoreList::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).
-It may also happen that C<Module::CoreList> has been modified in blead, and
-hence has a new version number already. (But make sure it is not the same
-number as a CPAN release.)
-
-Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
-entry, as that is likely to reflect the previous version number.
-
-=head4 Bump C<$Module::CoreList::TieHashDelta::VERSION>
-
-C<$Module::CoreList::TieHashDelta::VERSION> should always be equal to
-C<$Module::CoreList::VERSION>. Make sure the two versions match before
-proceeding.
-
-Edit the version number in the new
-C<< 'Module::CoreList::TieHashDelta' => 'X.YZ' >> entry, as that is likely to
-reflect the previous version number.
-
-=head4 Bump C<$Module::CoreList::Utils::VERSION>
-
-C<$Module::CoreList::Utils::VERSION> should always be equal to
-C<$Module::CoreList::VERSION>. Make sure the two versions match before
-proceeding.
-
-Edit the version number in the new
-C<< 'Module::CoreList::Utils' => 'X.YZ' >> entry, as that is likely to
-reflect the previous version number.
+ $ git diff dist/Module-CoreList/lib/Module/CoreList.pod
+ $ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm
=head4 Bump version in Module::CoreList F<Changes>
-Also edit Module::CoreList's new version number in its F<Changes>
-file.
+Also edit Module::CoreList's new version number in its F<Changes> file.
=head4 Add Module::CoreList version bump to perldelta
=head4 Update C<%Module::CoreList::released> and C<CAVEATS>
-In addition, if this is a final release (rather than a release candidate):
+For any release except an RC:
=over 4
(unless this is for MAINT; in which case commit it to blead first, then
cherry-pick it back).
- $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod
+ $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/Changes dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod dist/Module-CoreList/lib/Module/CoreList/Utils.pm
=head4 Rebuild and test
$ perl Porting/acknowledgements.pl v5.15.0..HEAD
-Fill in the "Updated Modules" section now that Module::CoreList is updated.
+Fill in the "New/Updated Modules" sections now that Module::CoreList is updated:
+
+ $ ./perl -Ilib Porting/corelist-perldelta.pl --mode=update pod/perldelta.pod
+
+Ideally, also fill in a summary of the major changes to each module for which
+an entry has been added by F<corelist-perldelta.pl>.
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
$ cp ..../blead/pod/perlhist.pod pod/
$ git commit -m 'sync perlhist from blead' pod/perlhist.pod
-=for checklist skip RC
-
=head3 update perlhist.pod
-I<You MUST SKIP this step for a RC release>
-
Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
David 5.10.1 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>.
+List yourself in the left-hand column, and if this is the first release
+that you've ever done, make sure that your name is listed in the section
+entitled C<THE KEEPERS OF THE PUMPKIN>.
I<If you're making a BLEAD-FINAL release>, also update the "SELECTED
RELEASE SIZES" section with the output of
people a small amount of download time and disk space, which adds
up.
+In order to produce the C<xz> tarball, XZ Utils are required. The C<xz>
+utility is included with most modern UNIX-type operating systems and
+is available for Cygwin. A Windows port is available from
+L<http://tukaani.org/xz/>.
+
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 status # and there's nothing lying around
+ $ cd root/of/perl/tree
+ $ make distclean # make sure distclean works
+ $ git clean -xdf # make sure perl and git agree on files
+ # git clean should not output anything!
+ $ git status # and there's nothing lying around
- $ perl Porting/makerel -b -s RC1 # for a release candidate
- $ perl Porting/makerel -b # for a final release
+ $ perl Porting/makerel -bx -s RC1 # for a release candidate
+ $ perl Porting/makerel -bx # 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.
+the MANIFEST files into it, sets the correct permissions on them, then
+tars it up as F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a
+C<tar.bz2> file. The C<-x> also produces a C<tar.xz> file.
If you're getting your tarball suffixed with -uncommitted and you're sure
your changes were all committed, you can override the suffix with:
=head4 Copy the tarball to a web server
-Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
+Copy the tarballs (.gz and possibly .bz2 and .xz) to a web server somewhere you
have access to.
=head4 Download the tarball to another machine
$ ./Configure -des && make all test
+ # Or for a development release:
+ $ ./Configure -Dusedevel -des && make all test
+
=head4 Run the test harness and install
Check that the test harness and install work on each test machine:
$ bin/cpan
+ # Or, perhaps:
+ $ bin/cpan5.xx.x
+
=head4 Install the Inline module with CPAN and test it
Try installing a popular CPAN module that's reasonably complex and that
has dependencies; for example:
- CPAN> install Inline
+ CPAN> install Inline::C
CPAN> quit
Check that your perl can run this:
git push
git branch -d release-5.xx.yy
+Note: The merge will create a merge commit if other changes have been pushed
+to blead while you've been working on your release branch. Do NOT rebase your
+branch to avoid the merge commit (as you might normally do when merging a
+small branch into blead) since doing so will invalidate the tag that you
+created earlier.
+
=head3 publish the release tag
Now that you've shipped the new perl release to PAUSE and pushed your changes
=head3 update epigraphs.pod
Add your quote to F<Porting/epigraphs.pod> and commit it.
-Your release announcement will probably not have reached the web-visible
-archives yet, so you won't be able to include the customary link to the
-release announcement yet.
+You can include the customary link to the release announcement even before your
+message reaches the web-visible archives by looking for the X-List-Archive
+header in your message after receiving it back via perl5-porters.
=head3 blog about your epigraph
=for checklist skip RC
+=head3 Release schedule
+
+I<You MUST SKIP this step for RC>
+
+Tick the entry for your release in F<Porting/release_schedule.pod>.
+
+=for checklist skip RC
+
=head3 Module::CoreList nagging
I<You MUST SKIP this step for RC>
=back
At this point you may want to compare the commit with a previous bump to
-see if they look similar. See commit 4eabcf701b for an example of a
+see if they look similar. See commit ba03bc34a4 for an example of a
previous version bump.
=for checklist skip MAINT RC
After bumping the version, follow the section L<"update INSTALL"> to
ensure all version number references are correct.
+(Note: The version is NOT bumped immediately after a MAINT release in order
+to avoid confusion and wasted time arising from bug reports relating to
+"intermediate versions" such as 5.20.1-and-a-bit: If the report is caused
+by a bug that gets fixed in 5.20.2 and this intermediate version already
+calls itself 5.20.2 then much time can be wasted in figuring out why there
+is a failure from something that "should have been fixed". If the bump is
+late then there is a much smaller window of time for such confusing bug
+reports to arise. (The opposite problem -- trying to figure out why there
+*is* a bug in something calling itself 5.20.1 when in fact the bug was
+introduced later -- shouldn't arise for MAINT releases since they should,
+in theory, only contain bug fixes but never regressions.))
+
=head3 clean build and test
Run a clean build and test to make sure nothing obvious is broken.
Copy the perldelta.pod for this release into blead; for example:
- $ cd ..../blead
- $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
- $ git add pod/perl5101delta.pod
+ $ cd ..../blead
+ $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
+ $ git add pod/perl5101delta.pod
+
+Don't forget to set the NAME correctly in the new file (e.g. perl5101delta
+rather than perldelta).
Edit F<pod/perl.pod> to add an entry for the file, e.g.:
$ git commit -a -m 'add perlXXXdelta'
$ git push origin ....
-=head3 copy perlhist.pod entries to blead
+=for checklist skip BLEAD-POINT
-XXX probably irrelevant for BLEAD-POINT
+=head3 copy perlhist.pod entries to blead
Make sure any recent F<pod/perlhist.pod> entries are copied to
F<perlhist.pod> on blead. e.g.
open up any ticket for modification and check the drop downs next to the
C<Perl Version> and C<Fixed In> labels.
+Here, try this link: L<https://rt.perl.org/Ticket/Modify.html?id=10000>
+
If the new version is not listed there, send an email to C<perlbug-admin at
perl.org> requesting this.
=head2 Building a release - the day after
-=head3 link announcement in epigraphs.pod
-
-Add, to your quote to F<Porting/epigraphs.pod>, a link to the release
-announcement in the web-visible mailing list archive. Commit it.
+=for checklist skip BLEAD-FINAL, MAINT, RC
-=head3 Update Module::CoreList
-
-XXX -- experimental in response to [perl #118195]
+=head3 update Module::CoreList
I<After a BLEAD-POINT release only>
After Module::CoreList has shipped to CPAN by the maintainer, update
Module::CoreList in the source so that it reflects the new blead
-version number.
+version number:
+
+=over 4
+
+=item *
+
+Update F<Porting/Maintainers.pl> to list the new DISTRIBUTION on CPAN,
+which should be identical to what is currently in blead.
+
+=item *
+
+Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm>,
+F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm> and
+F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
+
+=item *
+
+If you have a local CPAN mirror, run:
+
+ $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
+
+Otherwise, run:
+
+ $ ./perl -Ilib Porting/corelist.pl cpan
+
+This will update F<dist/Module-CoreList/lib/Module/CoreList.pm>,
+F<dist/Module-CoreList/lib/Module/CoreList.pod> and
+F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before,
+but this time adding new sections for the next BLEAD-POINT release.
+
+=item *
+
+Add the new $Module::CoreList::VERSION to
+F<dist/Module-CoreList/Changes>.
+
+=item *
+
+Update F<pod/perldelta.pod> to mention the upgrade to Module::CoreList.
+
+=item *
+
+Remake perl to get your changed .pm files propagated into F<lib/> and
+then run at least the F<dist/Module-CoreList/t/*.t> tests and the
+test_porting makefile target to check that they're ok.
+
+=item *
+
+Run
+
+ $ ./perl -Ilib -MModule::CoreList -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
+
+and check that it outputs "ok" to prove that Module::CoreList now knows
+about blead's current version.
+
+=item *
+
+Commit and push your changes.
+
+=back
=head3 check tarball availability
=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), and an appropriate mention in
-C</src/README.html> (which describes the latest versions in each branch,
-with links). BLEAD-POINT releases will not be mentioned.
+the new tarballs have appeared: There should be links in C</src/5.0>
+(which is accumulating all new versions), and (for BLEAD-FINAL and
+MAINT only) an appropriate mention in C</src/README.html> (which describes
+the latest versions in each stable branch, with links).
The C</src/5.0> links should appear automatically, some hours after upload.
If they don't, or the C</src> description is inadequate,
https://perl5.git.perl.org / perl5.git / blobdiff