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<@IGNORABLE> in F<Porting/Maintainer.pl>, and anything that
matches the C<EXCLUDED> section of the distro's entry in the C<%Modules>
hash.
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
=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
$ 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
the tarball and directory name:
$ cd root/of/perl/tree
- $ make distclean
+ $ 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
$ ./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:
=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
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.
$ 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.:
perl5101delta Perl changes in version 5.10.1
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/rt3/Ticket/Modify.html?id=10000>
+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