The Perl release 5.25.10

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

Building a release - advance action

dual-life CPAN module synchronisation

To see which core distro versions differ from the current CPAN versions:

    $ ./perl -Ilib Porting/core-cpan-diff -x -a

However, this only checks whether the version recorded in Porting/Maintainers.pl differs from the latest on CPAN. It doesn't tell you if the code itself has diverged from CPAN.

You can also run an actual diff of the contents of the modules, comparing core to CPAN, to ensure that there were no erroneous/extraneous changes that need to be dealt with. You do this by not passing the -x option:

    $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs

Passing -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 after perl is released.)

See also the -d and -v options for more detail (and the -u option as mentioned above). You'll probably want to use the -c cachedir option to avoid repeated CPAN downloads and may want to use -m file:///mirror/path if you made a local CPAN mirror. Note that a minicpan mirror won't actually work, 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-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 Porting/Maintainers.pl.

If you are making a MAINT release, run core-cpan-diff on both blead and maint, then diff the two outputs. Compare this with what you expect, and if necessary, fix things up. For example, you might think that both blead and maint are synchronised with a particular CPAN module, but one might have some extra changes.

How to sync a CPAN module with a cpan/ distro

In most cases, once a new version of a distribution shipped with core has been uploaded to CPAN, the core version thereof can be synchronized automatically with the program Porting/sync-with-cpan. (But see the comments at the beginning of that program. In particular, it has not yet been exercised on Windows as much as it has on Unix-like platforms.)

If, however, Porting/sync-with-cpan does not provide good results, follow the steps below.

  • Fetch the most recent version from CPAN.
  • Unpack the retrieved tarball. Rename the old directory; rename the new directory to the original name.
  • Restore any .gitignore file. This can be done by issuing git checkout .gitignore in the cpan/Distro directory.
  • Remove files we do not need. That is, remove any files that match the entries in @IGNORABLE in Porting/Maintainers.pl, and anything that matches the EXCLUDED section of the distro's entry in the %Modules hash.
  • Restore any files mentioned in the CUSTOMIZED section, using git checkout. Make any new customizations if necessary. Also, restore any files that are mentioned in @IGNORE, but were checked into the repository anyway.
  • For any new files in the distro, determine whether they are needed. If not, delete them, and list them in either EXCLUDED or @IGNORABLE. Otherwise, add them to MANIFEST, and run git add to add the files to the repository.
  • For any files that are gone, remove them from MANIFEST, and use git rm to tell git the files will be gone.
  • If the MANIFEST file was changed in any of the previous steps, run perl Porting/manisort --output MANIFEST.sort; mv MANIFEST.sort MANIFEST.
  • For any files that have an execute bit set, either remove the execute bit, or edit Porting/exec-bit.txt
  • Run make (or nmake on Windows), see if perl compiles.
  • Run the tests for the package.
  • Run the tests in t/porting (make test_porting).
  • Update the DISTRIBUTION entry in Porting/Maintainers.pl.
  • Run a full configure/build/test cycle.
  • If everything is ok, commit the changes.

For entries with a non-simple FILES section, or with a MAP, you may have to take more steps than listed above.

dual-life CPAN module stability

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)

   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)
monitor smoke tests for failures

Similarly, monitor the smoking of core tests, and try to fix. See http://smoke.procura.nl/index.html, http://perl5.test-smoke.org/ and http://perl.develop-help.com for a summary. See also http://www.nntp.perl.org/group/perl.daily-build.reports/ which has the raw reports.

Similarly, monitor the smoking of perl for compiler warnings, and try to fix.

monitor CPAN testers for failures

For any release except a BLEAD-POINT: Examine the relevant analysis report(s) at http://analysis.cpantesters.org/beforemaintrelease to see how the impending release is performing compared to previous releases with regard to building and testing CPAN modules.

That page accepts a query parameter, pair that takes a pair of colon-delimited versions to use for comparison. For example:

http://analysis.cpantesters.org/beforemaintrelease?pair=5.20.2:5.22.0%20RC1

update perldelta

Get perldelta in a mostly finished state.

Read Porting/how_to_write_a_perldelta.pod, and try to make sure that every section it lists is, if necessary, populated and complete. Copy edit the whole document.

You won't be able to automatically fill in the "Updated Modules" section until after Module::CoreList is updated (as described below in "update Module::CoreList").

Bump the version number

Do not do this yet for a BLEAD-POINT release! You will do this at the end of the release process.

Increase the version number (e.g. from 5.12.0 to 5.12.1).

For a release candidate for a stable perl, this should happen a week or two before the first release candidate to allow sufficient time for testing and smoking with the target version built into the perl executable. For subsequent release candidates and the final release, it is not necessary to bump the version further.

There is a tool to semi-automate this process:

    $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1

Remember that this tool is largely just grepping for '5.10.0' or whatever, so it will generate false positives. Be careful not change text like "this was fixed in 5.10.0"!

Use git status and git diff to select changes you want to keep.

Be particularly careful with INSTALL, which contains a mixture of 5.10.0-type strings, some of which need bumping on every release, and some of which need to be left unchanged. See below in "update INSTALL" for more details.

For the first RC release leading up to a BLEAD-FINAL release, update the description of which releases are now "officially" supported in pod/perlpolicy.pod.

When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the PERL_API_* constants in 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 PERL_API_* constants 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

This might not cause any new changes.

You may also need to regen opcodes:

 $ ./perl -Ilib regen/opcode.pl

Test your changes:

 $ git clean -xdf   # careful if you don't have local files to keep!
 $ ./Configure -des -Dusedevel
 $ make
 $ make test

Do note that at this stage, porting tests will fail. They will continue to fail until you've updated Module::CoreList, as described below.

Commit your changes:

 $ git status
 $ git diff
 B<review the delta carefully>

 $ 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 f7cf42bb69 for an example of a previous version bump.

When the version number is bumped, you should also update Module::CoreList (as described below in "update Module::CoreList") to reflect the new version number.

update INSTALL

Review and update INSTALL to account for the change in version number. The lines in INSTALL about "is not binary compatible with" may require a correct choice of earlier version to declare incompatibility with. These are in the "Changes and Incompatibilities" and "Coexistence with earlier versions of perl 5" sections.

Be particularly careful with the section "Upgrading from 5.X.Y or earlier". The "X.Y" needs to be changed to the most recent version that we are not binary compatible with.

For MAINT and BLEAD-FINAL releases, this needs to refer to the last release in the previous development cycle (so for example, for a 5.14.x release, this would be 5.13.11).

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). If the last release manager followed instructions, this should have already been done after the last blead release, so you may find nothing to do here.

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

Check more build configurations

Try running the full test suite against multiple Perl configurations. Here are some sets of Configure flags you can try:

  • -Duseshrplib -Dusesitecustomize
  • -Duserelocatableinc
  • -Dusethreads

If you have multiple compilers on your machine, you might also consider compiling with -Dcc=$other_compiler.

update perlport

perlport has a section currently named Supported Platforms that indicates which platforms are known to build in the current release. If necessary update the list and the indicated version number.

check a readonly build

Even before other prep work, follow the steps in "build the tarball" and test it locally. Because a perl source tarballs sets many files read-only, it could test differently than tests run from the repository. After you're sure permissions aren't a problem, delete the generated directory and tarballs.