perl-5.10.2 is released
post-release actions are performed, including creating new
- perl5103delta.pod
+ perldelta.pod
... the cycle continues ...
Check that your account is allowed to upload perl distros: goto
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
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. Also note that this tool
+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.
+
+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
-Also be careful of F<Porting/epigraphs.pod>, which has legacy version
-numbers that should not get changed.
+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.
Commit your changes:
Review and update INSTALL to account for the change in version number;
in particular, the "Coexistence with earlier versions of perl 5" section.
+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 *
I<You MUST SKIP this step for SNAPSHOT>
I<You MAY SKIP this step for SNAPSHOT>
Finalize the perldelta. In particular, fill in the Acknowledgements
-section.
+section. You can generate a list of contributors with checkAUTHORS.pl.
+For example:
+
+ $ git log --pretty=fuller v5.13.2..HEAD | \
+ perl Porting/checkAUTHORS.pl --who -
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.
- $ podchecker -warnings -warnings pod/perl5101delta.pod
- $ spell pod/perl5101delta.pod
+ $ podchecker -warnings -warnings pod/perldelta.pod
+ $ spell pod/perldelta.pod
Also, you may want to generate and view an HTML version of it to check
formatting, e.g.
- $ perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html
+ $ perl pod/pod2html pod/perldelta.pod > /tmp/perldelta.html
+
+Another good HTML preview option is http://search.cpan.org/pod2html
+
+If you make changes, be sure to commit them.
=item *
Make sure you have a gitwise-clean perl directory (no modified files,
unpushed commits etc):
+ $ git clean -dxf
$ git status
=item *
$ git commit -a -m 'make regen; make regen_perly'
+(XXX regen might be a problem depending on the bison version available.
+We need to get a wizard to give better instructions on what to do or not do.)
+
=item *
I<You MUST SKIP this step for SNAPSHOT>
-Update C<Module::Corelist> with module version data for the new release.
+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
-I<blead> and subsequently cherry-pick it.
+from the maint branch, but commit the C<CoreList.pm> changes in
+I<blead> and subsequently cherry-pick it. XXX need a better example
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
Then change to your perl checkout, and if necessary,
- $ make perl
+ $ 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
=item *
-I<You MUST SKIP this step for SNAPSHOT>
+I<You MUST SKIP this step for SNAPSHOT or BLEAD release>
Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
a final release, remove it. For example:
=item *
-If this is maint release, make sure F<Porting/mergelog> is saved and
-committed.
-
-=item *
-
Push all your recent commits:
$ git push origin ....
=item *
-Check that the C<perlbug> utility works. Try the following:
+Check that the L<perlbug> utility works. Try the following:
$ bin/perlbug
...
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 successfully indexed. Do not
-proceed any further until you are sure that the indexing of your uploads
-has been successful.
+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 *
=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.)
-
-=item *
-
-Check http://www.cpan.org/src/ to see if the new tarballs have appeared.
-They should appear automatically, but if they don't then ask Jarkko to look
-into it, since his scripts must have broken.
-
-=item *
-
-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
-http://dev.perl.org/perl5/
-
-=item *
-
I<You MUST SKIP this step for RC>
Remind the current maintainer of C<Module::CoreList> to push a new release
I<You MUST SKIP this step for RC>
-Bump the perlXYZdelta version number.
+Create a new perldelta.
-First, create a new empty perlNNNdelta.pod file for the current release + 1;
-see F<Porting/how_to_write_a_perldelta.pod>.
+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).
-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.
+Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>.
-Then commit this file. (If this new perldelta needs to get cherrypicked
-anywhere, this provides a clean base to merge from.)
+Now edit the moved delta file to change the C<NAME> from C<perldelta> to
+C<perlNNNdelta>.
-For example, assuming 5.10.2:
+Then create a new empty perldelta.pod file for the new release; see
+F<Porting/how_to_write_a_perldelta.pod>.
- $ cp -i Porting/perldelta_template.pod pod/perl5102delta.pod
- $ (edit it)
- $ git add pod/perl5102delta.pod
- $ git commit -m 'create perl5102delta'
+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.
+
+Then commit the move and the new file.
-Edit the previous delta file to change the C<NAME> from C<perldelta>
-to C<perlNNNdelta> and commit it. For example:
+For example, assuming you just released 5.10.1:
+ $ git mv pod/perldelta.pod pod/perl5101delta.pod
+ $ (edit pod/perl5101delta.pod to retitle)
$ git add pod/perl5101delta.pod
- $ git commit -m 'retitle perl5101delta'
+
+ $ 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.
-Edit F<pod.lst>: add the new entry, flagged as 'D', and unflag the previous
-entry from being 'D'; for example:
+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
+ -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
Then manually edit (F<vms/descrip_mms.template> to bump the version
in the following entry:
- [.pod]perldelta.pod : [.pod]perl5101delta.pod
+ [.pod]perl5101delta.pod : [.pod]perldelta.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
-
-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 'update TOC and perldelta references'
+ $ 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 ca8de22071 for an example of a
+see if they look similar. See commit 2b6e134265 for an example of a
previous version bump.
=item *
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 RC, BLEAD>
-
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,
I<You MUST SKIP this step for RC, BLEAD>
-Copy the perlNNNdelta.pod for this release into the other branches; for
+Copy the perldelta.pod for this release into the other branches; for
example:
- $ cp -i ../5.10.x/pod/perl5101delta.pod pod/ # for example
+ $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
$ git add pod/perl5101delta.pod
Edit F<pod.lst> to add an entry for the file, e.g.:
=back
+=head2 Building a release - the day after
+
+=over 4
+
+=item *
+
+Check L<http://www.cpan.org/src/> to see if the new tarballs have appeared.
+They should appear automatically, some hours after upload,
+but if they don't then ask Jarkko to look
+into it, since his scripts must have broken.
+
+=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 Jarkko to update the descriptions of which tarballs are current in
+L<http://www.cpan.org/src/README.html>, and Rafael to update
+L<http://dev.perl.org/perl5/>
+
+=item *
+
+Post the release announcement to use.perl.org.
+(if you don't have access rights to post news, ask someone like Rafael to
+do it for you.)
+
+=back
+
=head1 SOURCE
Based on