=head2 Module removals
-XXX Remove this section if inapplicable.
+XXX Remove this section if not applicable.
-The following modules will be removed from the core distribution in a future
-release, and will at that time need to be installed from CPAN. Distributions
-on CPAN which require these modules will need to list them as prerequisites.
+The following modules will be removed from the core distribution in a
+future release, and will at that time need to be installed from CPAN.
+Distributions on CPAN which require these modules will need to list them as
+prerequisites.
The core versions of these modules will now issue C<"deprecated">-category
-warnings to alert you to this fact. To silence these deprecation warnings,
+warnings to alert you to this fact. To silence these deprecation warnings,
install the modules in question from CPAN.
Note that these are (with rare exceptions) fine modules that you are encouraged
-to continue to use. Their disinclusion from core primarily hinges on their
+to continue to use. Their disinclusion from core primarily hinges on their
necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
not usually on concerns over their design.
=over
+=item XXX
+
XXX Note that deprecated modules should be listed here even if they are listed
as an updated module in the L</Modules and Pragmata> section.
XXX Changes which enhance performance without changing behaviour go here.
There may well be none in a stable release.
-[ List each enhancement as a =item entry ]
+[ List each enhancement as an =item entry ]
=over 4
XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
go here. If Module::CoreList is updated, generate an initial draft of the
-following sections using F<Porting/corelist-perldelta.pl>, which prints stub
-entries to STDOUT. Results can be pasted in place of the '=head2' entries
-below. A paragraph summary for important changes should then be added by hand.
-In an ideal world, dual-life modules would have a F<Changes> file that could be
-cribbed.
+following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
+for important changes should then be added by hand. In an ideal world,
+dual-life modules would have a F<Changes> file that could be cribbed.
+
+The list of new and updated modules is modified automatically as part of
+preparing a Perl release, so the only reason to manually add entries here is if
+you're summarising the important changes in the module update. (Also, if the
+manually-added details don't match the automatically-generated ones, the
+release manager will have to investigate the situation carefully.)
-[ Within each section, list entries as a =item entry ]
+[ Within each section, list entries as an =item entry ]
=head2 New Modules and Pragmata
=item *
-XXX
+XXX Remove this section if not applicable.
=back
L<XXX> has been upgraded from version A.xx to B.yy.
+If there was something important to note about this change, include that here.
+
=back
=head2 Removed Modules and Pragmata
=head2 Changes to Existing Documentation
+We have attempted to update the documentation to reflect the changes
+listed in this document. If you find any we have missed, send email
+to L<perlbug@perl.org|mailto:perlbug@perl.org>.
+
XXX Changes which significantly change existing files in F<pod/> go here.
However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
section.
+Additionally, the following selected changes have been made:
+
=head3 L<XXX>
=over 4
=head1 Utility Changes
XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
-Most of these are built within the directories F<utils> and F<x2p>.
+Most of these are built within the directory F<utils>.
-[ List utility changes as a =head3 entry for each utility and =item
+[ List utility changes as a =head2 entry for each utility and =item
entries for each change
Use L<XXX> with program names to get proper documentation linking. ]
-=head3 L<XXX>
+=head2 L<XXX>
=over 4
However, any platform-specific changes should be listed in the
L</Platform Support> section, instead.
-[ List changes as a =item entry ].
+[ List changes as an =item entry ].
=over 4
Changes to existing files in F<t/> aren't worth summarizing, although the bugs
that they represent may be covered elsewhere.
-[ List each test improvement as a =item entry ]
+XXX If there were no significant test changes, say this:
+
+Tests were added and changed to reflect the other additions and changes
+in this release.
+
+XXX If instead there were significant changes, say this:
+
+Tests were added and changed to reflect the other additions and
+changes in this release. Furthermore, these significant changes were
+made:
+
+[ List each test improvement as an =item entry ]
=over 4
XXX Any changes to platform support should be listed in the sections below.
-[ Within the sections, list each platform as a =item entry with specific
+[ Within the sections, list each platform as an =item entry with specific
changes as paragraphs below it. ]
=head2 New Platforms
significant internal changes for future core maintainers should be noted as
well.
-[ List each change as a =item entry ]
+[ List each change as an =item entry ]
=over 4
XXX Important bug fixes in the core language are summarized here. Bug fixes in
files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
-[ List each fix as a =item entry ]
+[ List each fix as an =item entry ]
=over 4
tests that had to be C<TODO>ed for the release would be noted here. Unfixed
platform specific bugs also go here.
-[ List each fix as a =item entry ]
+[ List each fix as an =item entry ]
=over 4
=back
+=head1 Errata From Previous Releases
+
+=over 4
+
+=item *
+
+XXX Add anything here that we forgot to add, or were mistaken about, in
+the perldelta of a previous release.
+
+=back
+
=head1 Obituary
-XXX If any significant core contributor has died, we've added a short obituary
-here.
+XXX If any significant core contributor or member of the CPAN community has
+died, add a short obituary here.
=head1 Acknowledgements
XXX Generate this with:
- perl Porting/acknowledgements.pl v5.19.1..HEAD
+ perl Porting/acknowledgements.pl v5.31.2..HEAD
=head1 Reporting Bugs
-If you find what you think is a bug, you might check the articles recently
-posted to the comp.lang.perl.misc newsgroup and the perl bug database at
-http://rt.perl.org/perlbug/ . There may also be information at
-http://www.perl.org/ , the Perl Home Page.
+If you find what you think is a bug, you might check the perl bug database
+at L<https://rt.perl.org/>. There may also be information at
+L<http://www.perl.org/>, the Perl Home Page.
If you believe you have an unreported bug, please run the L<perlbug> program
included with your release. Be sure to trim your bug down to a tiny but
sufficient test case. Your bug report, along with the output of C<perl -V>,
will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send it
-to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who will be
-able to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently distributed on
-CPAN.
+If the bug you are reporting has security implications which make it
+inappropriate to send to a publicly archived mailing list, then see
+L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
+for details of how to report the issue.
+
+=head1 Give Thanks
+
+If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
+you can do so by running the C<perlthanks> program:
+
+ perlthanks
+
+This will send an email to the Perl 5 Porters list with your show of thanks.
=head1 SEE ALSO