The Perl release 5.25.10

My checklist for the developer release 5.25.10 of the programming language Perl.

Building a release - on the day

re-check earlier actions

Review all the actions in the previous section, "Building a release - advance actions" to ensure they are all done and up-to-date.

create a release branch

For BLEAD-POINT releases, making a release from a release branch avoids the need to freeze blead during the release. This is less important for BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in those cases. Create the branch by running

    git checkout -b release-5.xx.yy
build a clean perl

Make sure you have a gitwise-clean perl directory (no modified files, unpushed commits etc):

    $ git status
    $ git clean -dxf

then configure and build perl so that you have a Makefile and porting tools:

    $ ./Configure -Dusedevel -des && make

For each Perl release since the previous release of the current branch, check for modules that have identical version numbers but different contents by running:

    $ ./perl -Ilib Porting/cmpVERSION.pl --tag=v5.X.YY

(This is done automatically by t/porting/cmp_version.t for the previous release of the current branch, but not for any releases from other branches.)

Any modules that fail will need a version bump, plus a nudge to the upstream maintainer for 'cpan' upstream modules.

update Module::CoreList
finalize perldelta

Finalize the perldelta. In particular, fill in the Acknowledgements section, which can be generated with something like:

    $ perl Porting/acknowledgements.pl v5.15.0..HEAD

Fill in the "New/Updated Modules" sections now that Module::CoreList is updated:

    $ ./perl -Ilib Porting/corelist-perldelta.pl \
        --mode=update pod/perldelta.pod

For a MAINT release use something like this instead:

    $ ./perl -Ilib Porting/corelist-perldelta.pl 5.020001 5.020002 \
        --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 corelist-perldelta.pl.

Re-read the perldelta to try to find any embarrassing typos and thinkos; remove any TODO or 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/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 -Ilib ext/Pod-Html/bin/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.

remove stale perldeltas

For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas from the BLEAD-POINT releases since the previous BLEAD-FINAL should have now been consolidated into the current perldelta, and hence are now just useless clutter. They can be removed using:

    $ git rm <file1> <file2> ...

For example, for RC0 of 5.16.0:

    $ cd pod
    $ git rm perldelta515*.pod
add recent perldeltas

For the first RC for a MAINT release, copy in any recent perldeltas from blead that have been added since the last release on this branch. This should include any recent maint releases on branches older than your one, but not newer. For example if you're producing a 5.14.x release, copy any perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from 5.16.x or higher. Remember to

    $ git add <file1> <file2> ...
update and commit perldelta files

If you have added or removed any perldelta files via the previous two steps, then edit pod/perl.pod to add/remove them from its table of contents, then run Porting/pod_rules.pl to propagate your changes there into all the other files that mention them (including MANIFEST). You'll need to git add the files that it changes.

Then build a clean perl and do a full test

    $ git status
    $ git clean -dxf
    $ ./Configure -Dusedevel -des
    $ make
    $ make test

Once all tests pass, commit your changes.

build a clean perl

If you skipped the previous step (adding/removing perldeltas), again, make sure you have a gitwise-clean perl directory (no modified files, unpushed commits etc):

    $ git status
    $ git clean -dxf

then configure and build perl so that you have a Makefile and porting tools:

    $ ./Configure -Dusedevel -des && make
synchronise from blead's perlhist.pod

For the first RC for a MAINT release, copy in the latest pod/perlhist.pod from blead; this will include details of newer releases in all branches. In theory, blead's version should be a strict superset of the one in this branch, but it's probably safest to examine the changes first, to ensure that there's nothing in this branch that was forgotten from blead. An easy way to do that is with git checkout -p, to selectively apply any changes from the blead version to your current branch:

    $ git fetch origin
    $ git checkout -p origin/blead pod/perlhist.pod
    $ git commit -m 'sync perlhist from blead' pod/perlhist.pod
update perlhist.pod

Add an entry to pod/perlhist.pod with the release date, e.g.:

    David    5.10.1       2009-Aug-06

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 THE KEEPERS OF THE PUMPKIN.

If you're making a BLEAD-FINAL release, also update the "SELECTED RELEASE SIZES" section with the output of Porting/perlhist_calculate.pl.

Be sure to commit your changes:

    $ git commit -m 'add new release to perlhist' pod/perlhist.pod
update patchlevel.h

You MUST SKIP this step for a BLEAD-POINT release

Update patchlevel.h to add a -RC1-or-whatever string; or, if this is a final release, remove it. For example:

     static const char * const local_patches[] = {
             NULL
    +        ,"RC1"
     #ifdef PERL_GIT_UNCOMMITTED_CHANGES
             ,"uncommitted-changes"
     #endif

Be sure to commit your change:

    $ git commit -m 'bump version to RCnnn' patchlevel.h
run makemeta to update META files
    $ ./perl -Ilib Porting/makemeta

Be sure to commit any changes (if applicable):

    $ git status   # any changes?
    $ git commit -m 'Update META files' META.*
build, test and check a fresh perl

Build perl, then make sure it passes its own test suite, and installs:

    $ git clean -xdf
    $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest

    # or if it's an odd-numbered version:
    $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest

    $ make test install

Check that the output of /tmp/perl-5.x.y-pretest/bin/perl -v and /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. Note that as they have been built from a git working directory, they will still identify themselves using git tags and commits. (Note that for an odd-numbered version, perl will install itself as perl5.x.y). perl -v will identify itself as:

 This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef))

where 5.X.Z is the latest tag, NNN the number of commits since this tag, and deadbeef commit of that tag.

Then delete the temporary installation.

create the release tag

Create the tag identifying this release (e.g.):

    $ 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.

build the tarball

Before you run the following, you might want to install 7-Zip (the p7zip-full package under Debian or the p7zip port on MacPorts) or the AdvanceCOMP suite (e.g. the advancecomp package under Debian, or the advancecomp port on macports - 7-Zip on Windows is the same code as AdvanceCOMP, so Windows users get the smallest files first time). These compress about 5% smaller than gzip and bzip2. Over the lifetime of your distribution this will save a lot of people a small amount of download time and disk space, which adds up.

In order to produce the xz tarball, XZ Utils are required. The xz utility is included with most modern UNIX-type operating systems and is available for Cygwin. A Windows port is available from http://tukaani.org/xz/.

IMPORTANT: if you are on OS X, you must export COPYFILE_DISABLE=1 to prevent OS X resource files from being included in your tarball. After creating the tarball following the instructions below, inspect it to ensure you don't have files like ._foobar.

Create a tarball. Use the -s option to specify a suitable suffix for the tarball and directory name:

 $ 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 -bx -s RC1            # for a release candidate
 $ perl Porting/makerel -bx                   # for the release itself

This creates the directory ../perl-x.y.z-RC1 or similar, copies all the MANIFEST files into it, sets the correct permissions on them, then tars it up as ../perl-x.y.z-RC1.tar.gz. With -b, it also creates a tar.bz2 file. The -x also produces a 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:

    $ perl Porting/makerel -b -s ''

XXX if we go for extra tags and branches stuff, then add the extra details here

Finally, clean up the temporary directory, e.g.

    $ rm -rf ../perl-x.y.z-RC1
test the tarball

Once you have a tarball it's time to test the tarball (not the repository).

monitor smokes

XXX This is probably irrelevant if working on a release branch, though MAINT or RC might want to push a smoke branch and wait.

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).

Then check that the smoke tests pass (particularly on Win32). If not, go back and fix things.

Note that for BLEAD-POINT releases this may not be practical. It takes a long time for the smokers to catch up, especially the Win32 smokers. This is why we have a RC cycle for MAINT and BLEAD-FINAL releases, but for BLEAD-POINT releases sometimes the best you can do is to plead with people on IRC to test stuff on their platforms, fire away, and then hope for the best.

upload to PAUSE

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.

    https://pause.perl.org/

(Login, then select 'Upload a file to CPAN')

If your workstation is not connected to a high-bandwidth, high-reliability connection to the Internet, you should probably use the "GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the new release from wherever you put it for testers to find it. This will eliminate anxious gnashing of teeth while you wait to see if your 15 megabyte HTTP upload successfully completes across your slow, twitchy cable modem.

You can make use of your home directory on dromedary for this purpose: http://users.perl5.git.perl.org/~USERNAME maps to /home/USERNAME/public_html, where USERNAME is your login account on dromedary.

Remember: if your upload is partially successful, you may need to contact a PAUSE administrator or even bump the version of perl.

Upload the .gz, .xz, and .bz2 versions of the tarball.

Do not proceed any further until you are sure that your tarballs are on CPAN. Check your authors directory www.cpan.org (the globally balanced "fast" mirror) to confirm that your uploads have been successful.

wait for indexing

You MUST SKIP this step for RC and BLEAD-POINT

Wait until you receive notification emails from the PAUSE indexer 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.

disarm patchlevel.h

You MUST SKIP this step for BLEAD-POINT release

Disarm the patchlevel.h change; for example,

     static const char * const local_patches[] = {
             NULL
    -        ,"RC1"
     #ifdef PERL_GIT_UNCOMMITTED_CHANGES
             ,"uncommitted-changes"
     #endif

Be sure to commit your change:

    $ git commit -m 'disarm RCnnn bump' patchlevel.h
announce to p5p

Mail p5p to announce your new release, with a quote you prepared earlier.

Use the template at Porting/release_announcement_template.txt

Send a carbon copy to noc@metacpan.org

merge release branch back to blead

Merge the (local) release branch back into master now, and delete it.

    git checkout blead
    git pull
    git merge release-5.xx.yy
    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.

publish the release tag

Now that you've shipped the new perl release to PAUSE and pushed your changes to the Perl master repository, it's time to publish the tag you created earlier too (e.g.):

    $ git push origin tag v5.11.0
update epigraphs.pod

Add your quote to Porting/epigraphs.pod and commit it. 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.

blog about your epigraph

If you have a blog, please consider writing an entry in your blog explaining why you chose that particular quote for your epigraph.

Release schedule

You MUST SKIP this step for RC

Tick the entry for your release in Porting/release_schedule.pod.

Module::CoreList nagging

You MUST SKIP this step for RC

Remind the current maintainer of Module::CoreList to push a new release to CPAN.

new perldelta

You MUST SKIP this step for RC

Create a new perldelta.

  • Confirm that you have a clean checkout with no local changes.
  • Run Porting/new-perldelta.pl
  • Run the git add commands it outputs to add new and modified files.
  • Verify that the build still works, by running ./Configure and make test_porting. (On Win32 use the appropriate make utility).
  • If t/porting/podcheck.t spots errors in the new pod/perldelta.pod, run ./perl -MTestInit t/porting/podcheck.t | less for more detail. Skip to the end of its test output to see the options it offers you.
  • When make test_porting passes, commit the new perldelta.

At this point you may want to compare the commit with a previous bump to see if they look similar. See commit ba03bc34a4 for an example of a previous version bump.

bump version

You MUST SKIP this step for RC and MAINT

If this was a BLEAD-FINAL release (i.e. the first release of a new maint series, 5.x.0 where x is even), then bump the version in the blead branch in git, e.g. 5.12.0 to 5.13.0.

First, add a new feature bundle to regen/feature.pl, initially by just copying the exiting entry, and bump the file's $VERSION (after the __END__ marker); e.g.

         "5.14" => [qw(switch say state unicode_strings)],
    +    "5.15" => [qw(switch say state unicode_strings)],

Run regen/feature.pl to propagate the changes to lib/feature.pm.

Then follow the section "Bump the version number" to bump the version in the remaining files and test and commit.

If this was a BLEAD-POINT release, then just follow the section "Bump the version number".

After bumping the version, follow the section "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.))

clean build and test

Run a clean build and test to make sure nothing obvious is broken.

In particular, Porting/perldelta_template.pod is intentionally exempted from podchecker tests, to avoid false positives about placeholder text. However, once it's copied to pod/perldelta.pod the contents can now cause test failures. Problems should be resolved by doing one of the following:

  1. Replace placeholder text with correct text.
  2. If the problem is from a broken placeholder link, you can add it to the array @perldelta_ignore_links in t/porting/podcheck.t. Lines containing such links should be marked with XXX so that they get cleaned up before the next release.
  3. Following the instructions output by t/porting/podcheck.t on how to update its exceptions database.
push commits

Finally, push any commits done above.

    $ git push origin ....
create maint branch

You MUST SKIP this step for RC, BLEAD-POINT, MAINT

If this was a BLEAD-FINAL release (i.e. 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.

Assuming you're using git 1.7.x or newer:

    $ git checkout -b maint-5.12 v5.12.0
    $ git push origin -u maint-5.12
make the maint branch available in the APC

Clone the new branch into /srv/gitcommon/branches on camel so the APC will receive its changes.

    $ git clone --branch maint-5.14 /gitroot/perl.git \
    ?  /srv/gitcommon/branches/perl-5.14.x
    $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x

And nag the sysadmins to make this directory available via rsync.

XXX Who are the sysadmins? Contact info?

copy perldelta.pod to blead

You MUST SKIP this step for RC, BLEAD-POINT

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

Don't forget to set the NAME correctly in the new file (e.g. perl5101delta rather than perldelta).

Edit pod/perl.pod to add an entry for the file, e.g.:

    perl5101delta               Perl changes in version 5.10.1

Then rebuild various files:

    $ perl Porting/pod_rules.pl

Finally, commit and push:

    $ git commit -a -m 'add perlXXXdelta'
    $ git push origin ....
copy perlhist.pod entries to blead

Make sure any recent pod/perlhist.pod entries are copied to perlhist.pod on blead. e.g.

    5.8.9         2008-Dec-14
Relax!

You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some much-needed rest and relaxation.

Thanks for releasing perl!