My checklist for the developer release 5.25.10 of the programming language Perl.
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
$ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
-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
-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.
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.
git checkout .gitignorein the cpan/Distro directory.
@IGNORABLEin Porting/Maintainers.pl, and anything that matches the
EXCLUDEDsection of the distro's entry in the
git checkout. Make any new customizations if necessary. Also, restore any files that are mentioned in
@IGNORE, but were checked into the repository anyway.
@IGNORABLE. Otherwise, add them to
MANIFEST, and run
git addto add the files to the repository.
MANIFEST, and use
git rmto tell git the files will be gone.
MANIFESTfile was changed in any of the previous steps, run
perl Porting/manisort --output MANIFEST.sort; mv MANIFEST.sort MANIFEST.
nmakeon Windows), see if
DISTRIBUTIONentry in Porting/Maintainers.pl.
For entries with a non-simple
FILES section, or with a
MAP, you may have to take more steps than listed above.
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)
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.
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:
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").
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
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.
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 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
Try running the full test suite against multiple Perl configurations. Here are some sets of Configure flags you can try:
If you have multiple compilers on your machine, you might also consider compiling with
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.
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.