This script is run as:
- perl Porting/make-rmg-checklist \
- --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod
+ perl Porting/make-rmg-checklist \
+ --version [5.x.y-RC#] > /tmp/rmg.pod
You can also pass the C<--html> flag to generate an HTML document instead of
POD.
- perl Porting/make-rmg-checklist --html \
- --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html
+ perl Porting/make-rmg-checklist --html \
+ --version [5.x.y-RC#] > /tmp/rmg.html
=head1 SYNOPSIS
...time passes...
a few weeks before the release, a number of steps are performed,
- including bumping the version to 5.10.2
+ including bumping the version to 5.10.2
...a few weeks pass...
perl-5.10.2 is released
post-release actions are performed, including creating new
- perldelta.pod
+ perldelta.pod
... the cycle continues ...
https://pause.perl.org/pause/query?ACTION=pause_04imprint
-=head3 search.cpan.org pumpkin status
+=head3 GitHub issue management access
-Make sure that search.cpan.org knows that you're allowed to upload
-perl distros. Contact Graham Barr to make sure that you're on the right
-list.
-
-=head3 rt.perl.org update access
-
-Make sure you have permission to close tickets on L<http://rt.perl.org/>
-so you can respond to bug report as necessary during your stint. If you
-don't, make an account (if you don't have one) and contact the pumpking
+Make sure you have permission to close tickets on L<https://github.com/Perl/perl5/issues>
+so you can respond to bug reports as necessary during your stint. If you
+don't, make a GitHub account (if you don't have one) and contact the pumpking
with your username to get ticket-closing permission.
=head3 git checkout and commit bit
you into the idea in the first place to figure out the best way to
resolve the issue.
-=head3 git clone of https://github.com/perlorg/perlweb
+=head3 web-based file share
+
+You will need to be able to share tarballs with #p5p members for
+pre-release testing, and you may wish to upload to PAUSE via URL.
+Make sure you have a way of sharing files, such as a web server or
+file-sharing service.
+
+Porters have access to the "dromedary" server (users.perl5.git.perl.org),
+which has a F<public_html> directory to share files with.
+(L<http://users.perl5.git.perl.org/~username/perl-5.xx.y.tar.gz>)
-For updating the L<http://dev.perl.org> web pages, either a Github account or
-sweet-talking somebody with a Github account into obedience is needed. This
-is only needed on the day of the release or shortly afterwards.
+If you use Dropbox, you can append "raw=1" as a parameter to their usual
+sharing link to allow direct download (albeit with redirects).
=head3 Quotation for release announcement epigraph
You will need a quotation to use as an epigraph to your release announcement.
+It will live forever (along with Perl), so make it a good one.
+
+=head3 Install the previous version of perl
+
+During the testing phase of the release you have created, you will be
+asked to compare the installed files with a previous install. Save yourself
+some time on release day, and have a (clean) install of the previous
+version ready.
=head2 Building a release - advance actions
to CPAN, to ensure that there were no erroneous/extraneous changes that need to
be dealt with. You do this by not passing the C<-x> option:
- $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
+ $ ./perl -Ilib Porting/core-cpan-diff -a -o ~/corediffs
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
and maint are synchronised with a particular CPAN module, but one might
have some extra changes.
-=head3 How to sync a CPAN module with a cpan/ distro
+In any case, any cpan-first distribution that is listed as having files
+"Customized for blead" in the output of cpan-core-diff should have requests
+submitted to the maintainer(s) to make a cpan release to catch up with blead.
+
+Additionally, all files listed as "modified" but not "customized for blead"
+should have entries added under the C<CUSTOMIZED> key in
+F<Porting/Maintainers.pl>, as well as checksums updated via:
+
+ cd t; ../perl -I../lib porting/customized.t --regen
+
+=head4 Sync CPAN modules with the corresponding cpanE<sol> 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 F<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, F<Porting/sync-with-cpan> does not provide good results, follow
+the steps below.
=over 4
=item *
Remove files we do not need. That is, remove any files that match the
-entries in C<@IGNORABLE> in F<Porting/Maintainer.pl>, and anything that
+entries in C<@IGNORABLE> in F<Porting/Maintainers.pl>, and anything that
matches the C<EXCLUDED> section of the distro's entry in the C<%Modules>
hash.
=item *
For any new files in the distro, determine whether they are needed.
-If not, delete them, and list them in either C<EXCLUDED> or C<@INGORE>.
+If not, delete them, and list them in either C<EXCLUDED> or C<@IGNORABLE>.
Otherwise, add them to C<MANIFEST>, and run C<git add> to add the files
to the repository.
=item *
-Run the tests in F<t/porting>.
+Run the tests in F<t/porting> (C<make test_porting>).
=item *
For entries with a non-simple C<FILES> section, or with a C<MAP>, you
may have to take more steps than listed above.
-F<Porting/sync-with-cpan> is a script that automates most of the steps
-above; but see the comments at the beginning of the file. In particular,
-it has not yet been exercised on Windows, but will certainly require a set
-of Unix tools such as Cygwin, and steps that run C<make> will need to run
-C<nmake> instead.
-
-=head3 dual-life CPAN module stability
+=head3 Ensure dual-life CPAN module stability
-Ensure dual-life CPAN modules are stable, which comes down to:
+This 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)
+ for each module that fails its regression tests on $current
+ did it fail identically on $previous?
+ if yes, "SEP" (Somebody Else's Problem, but try to make sure a
+ bug ticket is filed)
+ else work out why it failed (a bisect is useful for this)
- attempt to group failure causes
+ 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)
+ 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)
=head3 monitor smoke tests for failures
Similarly, monitor the smoking of core tests, and try to fix. See
-L<http://doc.procura.nl/smoke/index.html> and L<http://perl5.test-smoke.org/>
-for a summary. See also
-L<http://www.nntp.perl.org/group/perl.daily-build.reports/> which has
+L<https://tux.nl/perl5/smoke/index.html>, L<https://perl5.test-smoke.org/>
+and L<http://perl.develop-help.com> for a summary. See also
+L<https://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 checklist skip BLEAD-POINT
+
+=head3 monitor CPAN testers for failures
+
+For any release except a BLEAD-POINT: Examine the relevant analysis report(s)
+at L<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, C<pair> that takes a pair of
+colon-delimited versions to use for comparison. For example:
+
+L<http://analysis.cpantesters.org/beforemaintrelease?pair=5.20.2:5.22.0%20RC1>
+
+=head3 Monitor Continuous Integration smokers
+
+Currently both "Travis CI" and "GitHub Actions" smokers are setup.
+Their current status is available at:
+
+L<https://github.com/Perl/perl5/actions>
+L<https://travis-ci.org/Perl/perl5>
+
=head3 update perldelta
Get perldelta in a mostly finished state.
-Read
F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
+Read F<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.
=head3 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.
+the release process (after building the final tarball, tagging etc).
Increase the version number (e.g. from 5.12.0 to 5.12.1).
There is a tool to semi-automate this process:
- $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1
+ $ ./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
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.
-The line in F<INSTALL> about "is binary incompatible with" requires a
-correct choice of earlier version to declare incompatibility with.
+See below in L<"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
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
-make is 100% binary compatible to an earlier release. When releasing a MAINT
-perl version, the C<PERL_API_*> constants C<MUST NOT> be changed as we aim
-to guarantee binary compatibility in maint branches.
+make is 100% binary compatible to an earlier release. Note: for BLEAD-POINT
+releases the bump should have already occurred at the end of the previous
+release and this is something you would have to do at the very end.
+When releasing a MAINT perl version, the C<PERL_API_*> constants C<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 -Ilib regen/opcode.pl
-You may have to add stub entries in C<%Module::CoreList::version>,
-C<%Module::CoreList::deprecated> and C<%Module::CoreList::Utils::delta>.
-If so, you must up their version numbers as well.
-
Test your changes:
$ git clean -xdf # careful if you don't have local files to keep!
$ 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
=head3 update INSTALL
-Review and update INSTALL to account for the change in version number;
-in particular, the "Coexistence with earlier versions of perl 5" section.
+Review and update INSTALL to account for the change in version number.
+INSTALL for a BLEAD-POINT release should already contain the expected version.
+The lines in F<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
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).
+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.
=head3 Check copyright years
Check that the copyright years are up to date by running:
- $ ./perl t/porting/copyright.t --now
+ $ pushd t; ../perl -I../lib 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
If you have multiple compilers on your machine, you might also consider
compiling with C<-Dcc=$other_compiler>.
+You can also consider pushing the repo to GitHub where Travis CI is enabled
+which would smoke different flavors of Perl for you.
+
=head3 update perlport
L<perlport> has a section currently named I<Supported Platforms> that
=head3 check a readonly build
-Even before other prep work, follow the steps in L<build the tarball> and test
+Even before other prep work, follow the steps in L</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.
+
=head2 Building a release - on the day
This section describes the actions required to make a release
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
+ git checkout -b release-5.xx.yy
=head3 build a clean perl
$ ./Configure -Dusedevel -des && make
+=head3 Check module versions
+
+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 F<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.
+
=head3 update Module::CoreList
=head4 Bump Module::CoreList* $VERSIONs
-If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this for
-every RC; in RC1, bump the version to a new clean number that will
+If necessary, bump C<$VERSION> (there's no need to do this
+for every RC; in RC1, bump the version to a new clean number that will
appear in the final release, and leave as-is for the later RCs and final).
It may also happen that C<Module::CoreList> has been modified in blead, and
hence has a new version number already. (But make sure it is not the same
number as a CPAN release.)
-C<$Module::CoreList::TieHashDelta::VERSION> and
C<$Module::CoreList::Utils::VERSION> should always be equal to
C<$Module::CoreList::VERSION>. If necessary, bump those two versions to match
before proceeding.
-The files to modify are: F<dist/Module-CoreList/lib/Module/CoreList.pm>,
-F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> and
-F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm>.
+Once again, the files to modify are:
+
+=over 4
+
+=item *
+
+F<dist/Module-CoreList/lib/Module/CoreList.pm>
+
+=item *
+
+F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>
+
+=back
=head4 Update C<Module::CoreList> with module version data for the new release.
on HTTP::Tiny to fetch package metadata remotely.
(If you'd prefer to have a full CPAN mirror, see
-http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
+L<https://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN>)
-Then change to your perl checkout, and if necessary,
+Change to your perl checkout, and if necessary,
$ make
badly-indexed CPAN modules unrelated to the modules actually in core.
Assuming all goes well, it will update
F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly
-F<dist/Module-CoreList/lib/Module/CoreList.pod> and/or
F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
Check those files over carefully:
$ git diff dist/Module-CoreList/lib/Module/CoreList.pm
- $ git diff dist/Module-CoreList/lib/Module/CoreList.pod
$ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm
=head4 Bump version in Module::CoreList F<Changes>
Also edit Module::CoreList's new version number in its F<Changes> file.
+This file is F<dist/Module-CoreList/Changes>.
+(BLEAD-POINT releases should have had this done already as a post-release
+action from the last commit.)
=head4 Add Module::CoreList version bump to perldelta
-Add a perldelta entry for the new Module::CoreList version.
+Add a perldelta entry for the new Module::CoreList version. You only
+need to do this if you want to add notes about the changes included
+with this version of Module::CoreList. Otherwise, its version bump
+will be automatically filled in below in L</finalize perldelta>.
=for checklist skip RC
-=head4 Update C<%Module::CoreList::released> and C<CAVEATS>
-
-For any release except an RC:
-
-=over 4
-
-=item *
-
-Update this version's entry in the C<%released> hash with today's date.
-
-=item *
-
-Make sure that the script has correctly updated the C<CAVEATS> section
-(Note, the C<CAVEATS> section is in
-F<dist/Module-CoreList/lib/Module/CoreList.pod>)
+=head4 Update C<%Module::CoreList::released>
-=back
+For any release except an RC: Update this version's entry in the C<%released>
+hash with today's date.
=head4 Commit Module::CoreList changes
(unless this is for MAINT; in which case commit it to blead first, then
cherry-pick it back).
- $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/Changes dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod dist/Module-CoreList/lib/Module/CoreList/Utils.pm
+ $ git commit -m 'Update Module::CoreList for 5.x.y' \
+ dist/Module-CoreList/Changes \
+ dist/Module-CoreList/lib/Module/CoreList.pm \
+ dist/Module-CoreList/lib/Module/CoreList/Utils.pm
=head4 Rebuild and test
-Build and test to get the changes into the currently built lib directory and to ensure
-all tests are passing.
+Build and test to get the changes into the currently built lib directory and to
+ensure all tests are passing.
=head3 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
+ $ perl Porting/acknowledgements.pl v5.15.0..HEAD
-Fill in the "New/Updated Modules" sections 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
+ $ ./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 F<corelist-perldelta.pl>.
$ podchecker -warnings -warnings pod/perldelta.pod
$ spell pod/perldelta.pod
+ $ aspell list < pod/perldelta.pod | sort -u
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
+ $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > \
+ ~/perldelta.html
-Another good HTML preview option is http://search.cpan.org/pod2html
+You can add pod links for GitHub issue references thusly:
+
+ $ perl -p -i -e'BEGIN{undef $/}; s{(GH\s+#)(\d+)}{L<$1$2|https://github.com/Perl/perl5/issues/$2>}mg' pod/perldelta.pod
If you make changes, be sure to commit them.
Once all tests pass, commit your changes.
+=head3 final check of perldelta placeholders
+
+Check for any 'XXX' leftover section in the perldelta.
+Either fill them or remove these sections appropriately.
+
+ $ git grep XX pod/perldelta.pod
+
=head3 build a clean perl
If you skipped the previous step (adding/removing perldeltas),
For the first RC for a MAINT release, copy in the latest
F<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 diff them
-first to ensure that there's nothing in this branch that was forgotten
-from blead:
-
- $ diff pod/perlhist.pod ..../blead/pod/perlhist.pod
- $ cp ..../blead/pod/perlhist.pod pod/
+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 C<< 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
=head3 update perlhist.pod
static const char * const local_patches[] = {
NULL
+ ,"RC1"
- PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
+ #ifdef PERL_GIT_UNCOMMITTED_CHANGES
+ ,"uncommitted-changes"
+ #endif
Be sure to commit your change:
Create the tag identifying this release (e.g.):
- $ git tag v5.11.0 -m "First release of the v5.11 series!"
+ $ git tag v5.11.0 -m 'First release of the v5.11 series!'
It is B<VERY> important that from this point forward, you not push
your git changes to the Perl master repository. If anything goes
In order to produce the C<xz> tarball, XZ Utils are required. The C<xz>
utility is included with most modern UNIX-type operating systems and
is available for Cygwin. A Windows port is available from
-L<http://tukaani.org/xz/>.
+L<https://tukaani.org/xz/>.
+
+B<IMPORTANT>: if you are on OS X, you must export C<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 F<._foobar>.
Create a tarball. Use the C<-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
+ $ 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 --ignored # and there's nothing lying around
- $ perl Porting/makerel -bx -s RC1 # for a release candidate
- $ perl Porting/makerel -bx # for a final release
+ $ perl Porting/makerel -x -s RC1 # for a release candidate
+ $ perl Porting/makerel -x # for the release itself
-This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
+This creates the directory F<../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 F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a
-C<tar.bz2> file. The C<-x> also produces a C<tar.xz> file.
+tars it up as F<../perl-x.y.z-RC1.tar.gz>. The C<-x> also produces a
+C<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 ''
+ $ perl Porting/makerel -x -s ''
XXX if we go for extra tags and branches stuff, then add the extra details
here
=head4 Copy the tarball to a web server
-Copy the tarballs (.gz and possibly .bz2 and .xz) to a web server somewhere you
-have access to.
+Copy the tarballs (.gz and .xz) to a web server somewhere you have access to.
-=head4 Download the tarball to another machine
+=head4 Download the tarball to another machine and unpack it
Download the tarball to some other machine. For a release candidate,
you really want to test your tarball on two or more different platforms
-and architectures. The #p5p IRC channel on irc.perl.org is a good place
-to find willing victims.
+and architectures.
+
+=head4 Ask #p5p to test the tarball on different platforms
+
+Once you've verified the tarball can be downloaded and unpacked,
+ask the #p5p IRC channel on irc.perl.org for volunteers to test the
+tarballs on whatever platforms they can.
+
+If you're not confident in the tarball, you can defer this step until after
+your own tarball testing, below.
=head4 Check that F<Configure> works
Check that basic configuration and tests work on each test machine:
- $ ./Configure -des && make all test
+ $ ./Configure -des && make all minitest test
# Or for a development release:
- $ ./Configure -Dusedevel -des && make all test
+ $ ./Configure -Dusedevel -des && make all minitest test
=head4 Run the test harness and install
Check that the test harness and install work on each test machine:
$ make distclean
- $ ./Configure -des -Dprefix=/install/path && make all test_harness install
+ $ ./Configure -des -Dprefix=/install/path && \
+ make all test_harness install
$ cd /install/path
+(Remember C<-Dusedevel> above, for a development release.)
+
=head4 Check C<perl -v> and C<perl -V>
Check that the output of C<perl -v> and C<perl -V> are as expected,
=head4 Run the Installation Verification Procedure utility
- $ ./perl utils/perlivp
+ $ ./perl -Ilib ./perlivp
+ # Or, perhaps:
+ $ ./perl5.x.y ./perlivp5.x.y
...
All tests successful.
$
find . -type f | sort > /tmp/f2
diff -u /tmp/f[12]
+=head4 Disable C<local::lib> if it's turned on
+
+If you're using C<local::lib>, you should reset your environment before
+performing these actions:
+
+ $ unset PERL5LIB PERL_MB_OPT PERL_LOCAL_LIB_ROOT PERL_MM_OPT
+
=head4 Bootstrap the CPAN client
Bootstrap the CPAN client on the clean install:
Check that your perl can run this:
- $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
+ $ bin/perl -Ilib -lwe "use Inline C => q[int f() { return 42;}]; print f"
42
$
(edit report)
Action (Send/Display/Edit/Subject/Save to File): f
Name of file to save message in [perlbug.rep]:
- Action (Send/Display/Edit/Subject/Save to File): q
+ Action (Send/Display/Edit/Subject/Save to File): Q
and carefully examine the output (in F<perlbug.rep]>), especially
the "Locally applied patches" section. If everything appears okay, then
https://pause.perl.org/
-(Login, then select 'Upload a file to CPAN')
+(Log in, 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
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
+cable modem.
+
+You can make use of your home directory on dromedary for
this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
F</home/USERNAME/public_html>, where F<USERNAME> is your login account
-on dromedary. I<Remember>: if your upload is partially successful, you
+on dromedary.
+
+I<Remember>: if your upload is partially successful, you
may need to contact a PAUSE administrator or even bump the version of perl.
-Upload both the .gz and .bz2 versions of the tarball.
+Upload the .gz and .xz versions of the tarball.
+
+Note: You can also use the command-line utility to upload your tarballs, if
+you have it configured:
+
+ cpan-upload perl-5.X.Y.tar.gz
+ cpan-upload perl-5.X.Y.tar.xz
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.
+Check your authors directory metacpan.org to confirm that your uploads have
+been successful.
+
+ https://metacpan.org/author/YOUR_PAUSE_ID
=for checklist skip RC BLEAD-POINT
static const char * const local_patches[] = {
NULL
- ,"RC1"
- PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
+ #ifdef PERL_GIT_UNCOMMITTED_CHANGES
+ ,"uncommitted-changes"
+ #endif
Be sure to commit your change:
=head3 announce to p5p
-Mail p5p to announce your new release, with a quote you prepared earlier.
+Mail perl5-porters@perl.org to announce your new release, with a quote you prepared earlier.
+Get the SHA1 digests from the PAUSE email responses.
Use the template at Porting/release_announcement_template.txt
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
+ 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
If you have a blog, please consider writing an entry in your blog explaining
why you chose that particular quote for your epigraph.
+=head3 update the link to the latest perl on perlweb
+
+Submit a pull request to L<https://github.com/perlorg/perlweb> to update the
+link in F<docs/dev/perl5/index.html> to point to your release.
+
+=for checklist skip RC
+
+=head3 Release schedule
+
+I<You MUST SKIP this step for RC>
+
+Tick the entry for your release in F<Porting/release_schedule.pod>.
+
=for checklist skip RC
=head3 Module::CoreList nagging
=item *
-Run F<Porting/new-perldelta.pl>
+Run:
+ perl Porting/new-perldelta.pl
=item *
When C<make test_porting> passes, commit the new perldelta.
+ git commit -m'new perldelta for 5.X.Y'
+
=back
At this point you may want to compare the commit with a previous bump to
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.14" => [qw(switch say state unicode_strings)],
+ "5.15" => [qw(switch say state unicode_strings)],
Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>.
=head3 clean build and test
-Run a clean build and test to make sure nothing obvious is broken.
+Run a clean build and test to make sure nothing obvious is broken. This is
+very important, as commands run after this point must be run using the perl
+executable built with the bumped version number.
+
+ $ git clean -xdf
+ $ ./Configure -des -Dusedevel
+ $ make
+ $ make test
In particular, F<Porting/perldelta_template.pod> is intentionally exempted
from podchecker tests, to avoid false positives about placeholder text.
However, once it's copied to F<pod/perldelta.pod> the contents can now
-cause test failures. Problems should resolved by doing one of the
+cause test failures. Problems should be resolved by doing one of the
following:
=over
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
+ $ 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
Make sure any recent F<pod/perlhist.pod> entries are copied to
F<perlhist.pod> on blead. e.g.
- 5.8.9 2008-Dec-14
-
-=head3 bump RT version number
-
-Log into http://rt.perl.org/ and check whether the new version is in the RT
-fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is to
-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/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.
+ 5.8.9 2008-Dec-14
=head3 Relax!
=head2 Building a release - the day after
-=for checklist skip BLEAD-FINAL, MAINT, RC
+=for checklist skip BLEAD-FINAL MAINT RC
=head3 update Module::CoreList
=item *
-Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm>,
-F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm> and
-F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
+Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm>
+and F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
=item *
$ ./perl -Ilib Porting/corelist.pl cpan
-This will update F<dist/Module-CoreList/lib/Module/CoreList.pm>,
-F<dist/Module-CoreList/lib/Module/CoreList.pod> and
+This will update F<dist/Module-CoreList/lib/Module/CoreList.pm> and
F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before,
but this time adding new sections for the next BLEAD-POINT release.
=item *
-Update F<pod/perldelta.pod> to mention the upgrade to Module::CoreList.
-
-=item *
-
Remake perl to get your changed .pm files propagated into F<lib/> and
then run at least the F<dist/Module-CoreList/t/*.t> tests and the
test_porting makefile target to check that they're ok.
Run
- $ ./perl -Ilib -MModule::CoreList -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
+ $ ./perl -Ilib -MModule::CoreList \
+ -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
and check that it outputs "ok" to prove that Module::CoreList now knows
about blead's current version.
=item *
-Check your author directory under L<http://www.cpan.org/authors/id/>
+Check your author directory under L<https://www.cpan.org/authors/id/>
to ensure that the tarballs are available on the website.
=item *
-Check C</src> on CPAN (on a fast mirror) to ensure that links to
-the new tarballs have appeared: There should be links in C</src/5.0>
+Check F</src> on CPAN (on a fast mirror) to ensure that links to
+the new tarballs have appeared: There should be links in F</src/5.0>
(which is accumulating all new versions), and (for BLEAD-FINAL and
-MAINT only) an appropriate mention in C</src/README.html> (which describes
+MAINT only) an appropriate mention in F</src/README.html> (which describes
the latest versions in each stable branch, with links).
-The C</src/5.0> links should appear automatically, some hours after upload.
-If they don't, or the C</src> description is inadequate,
+The F</src/5.0> links should appear automatically, some hours after upload.
+If they don't, or the F</src> description is inadequate,
ask Ask <ask@perl.org>.
=item *
-Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
+Check L<https://www.cpan.org/src/> to ensure that the F</src> updates
have been correctly mirrored to the website.
If they haven't, ask Ask <ask@perl.org>.
=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/>.
+Check L<https://search.cpan.org> to see if it has indexed the distribution.
+It should be visible at a URL like C<https://search.cpan.org/dist/perl-5.10.1/>.
=back
-=for checklist skip RC
-
-=head3 update dev.perl.org
-
-I<You MUST SKIP this step for a RC release>
-
-In your C<perlweb> repository, link to the new release. For a new
-latest-maint release, edit F<docs/shared/tpl/stats.html>. Otherwise,
-edit F<docs/dev/perl5/index.html>.
-
-Then make a pull request to Leo Lapworth. If this fails for some reason
-and you cannot cajole anybody else into submitting that change, you can
-mail Leo as last resort.
-
-This repository can be found on L<github|https://github.com/perlorg/perlweb>.
-
=head3 update release manager's guide
Go over your notes from the release (you did take some, right?) and update
=head1 SOURCE
Based on
-http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
+L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html>,
plus a whole bunch of other sources, including private correspondence.
=cut
https://perl5.git.perl.org / perl5.git / blobdiff