New perldelta

(not cherry picked from commit 0382c61de115275c09bf1fbe39aa02e6118da28c
because a different sequence of events means that that commit made the
next perldelta "perl5330delta" rather than "perl5321delta" as needed here)

10 files changed, 2111 insertions, 1662 deletions

diff --git a/MANIFEST b/MANIFEST
index 946b8f164c..c0e79c571d 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -5193,6 +5193,7 @@ pod/perl5300delta.pod		Perl changes in version 5.30.0
 pod/perl5301delta.pod		Perl changes in version 5.30.1
 pod/perl5302delta.pod		Perl changes in version 5.30.2
 pod/perl5303delta.pod		Perl changes in version 5.30.3
+pod/perl5320delta.pod           Perl changes in version 5.32.0
 pod/perl561delta.pod		Perl changes in version 5.6.1
 pod/perl56delta.pod		Perl changes in version 5.6
 pod/perl581delta.pod		Perl changes in version 5.8.1
diff --git a/Makefile.SH b/Makefile.SH
index f77f170a0c..124db32a13 100755
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -589,7 +589,7 @@ esac
 
 $spitshell >>$Makefile <<'!NO!SUBS!'
 
-perltoc_pod_prereqs = extra.pods pod/perl5320delta.pod pod/perlapi.pod pod/perlintern.pod pod/perlmodlib.pod pod/perluniprops.pod
+perltoc_pod_prereqs = extra.pods pod/perl5321delta.pod pod/perlapi.pod pod/perlintern.pod pod/perlmodlib.pod pod/perluniprops.pod
 generated_pods = pod/perltoc.pod $(perltoc_pod_prereqs)
 generated_headers = uudmap.h bitcount.h mg_data.h
 
@@ -1153,9 +1153,9 @@ pod/perlintern.pod: $(MINIPERL_EXE) autodoc.pl embed.fnc
 pod/perlmodlib.pod: $(MINIPERL_EXE) pod/perlmodlib.PL MANIFEST
 	$(MINIPERL) pod/perlmodlib.PL -q
 
-pod/perl5320delta.pod: pod/perldelta.pod
-	$(RMS) pod/perl5320delta.pod
-	$(LNS) perldelta.pod pod/perl5320delta.pod
+pod/perl5321delta.pod: pod/perldelta.pod
+	$(RMS) pod/perl5321delta.pod
+	$(LNS) perldelta.pod pod/perl5321delta.pod
 
 extra.pods: $(MINIPERL_EXE)
 	-@test ! -f extra.pods || rm -f `cat extra.pods`
diff --git a/pod/.gitignore b/pod/.gitignore
index 54fa65f4c9..048b24d6fd 100644
--- a/pod/.gitignore
+++ b/pod/.gitignore
@@ -49,7 +49,7 @@
 /roffitall
 
 # generated
-/perl5320delta.pod
+/perl5321delta.pod
 /perlapi.pod
 /perlintern.pod
 /perlmodlib.pod
diff --git a/pod/perl5320delta.pod b/pod/perl5320delta.pod
new file mode 100644
index 0000000000..7861d7ee70
--- /dev/null
+++ b/pod/perl5320delta.pod
@@ -0,0 +1,1919 @@
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+perl5320delta - what is new for perl v5.32.0
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.30.0 release and the 5.32.0
+release.
+
+If you are upgrading from an earlier release such as 5.28.0, first read
+L<perl5300delta>, which describes differences between 5.28.0 and 5.30.0.
+
+=head1 Core Enhancements
+
+=head2 The isa Operator
+
+A new experimental infix operator called C<isa> tests whether a given object
+is an instance of a given class or a class derived from it:
+
+    if( $obj isa Package::Name ) { ... }
+
+For more detail see L<perlop/Class Instance Operator>.
+
+=head2 Unicode 13.0 is supported
+
+See L<https://www.unicode.org/versions/Unicode13.0.0/> for details.
+
+=head2 Chained comparisons capability
+
+Some comparison operators, as their associativity, I<chain> with some
+operators of the same precedence (but never with operators of different
+precedence).
+
+    if ( $x < $y <= $z ) {...}
+
+behaves exactly like:
+
+    if ( $x < $y && $y <= $z ) {...}
+
+(assuming that C<"$y"> is as simple a scalar as it looks.)
+
+You can read more about this in L<perlop> under
+L<perlop/Operator Precedence and Associativity>.
+
+=head2 New Unicode properties C<Identifier_Status> and C<Identifier_Type> supported
+
+Unicode has revised its regular expression requirements:
+L<https://www.unicode.org/reports/tr18/tr18-21.html>.
+As part of that they are wanting more properties to be exposed, ones
+that aren't part of the strict UCD (Unicode character database). These
+two are used for examining inputs for security purposes. Details on
+their usage is at L<https://www.unicode.org/reports/tr39/>.
+
+=head2 It is now possible to write C<qr/\p{Name=...}/>, or
+C<qr!\p{na=/(SMILING|GRINNING) FACE/}!>
+
+The Unicode Name property is now accessible in regular expression
+patterns, as an alternative to C<\N{...}>.
+A comparison of the two methods is given in
+L<perlunicode/Comparison of \N{...} and \p{name=...}>.
+
+The second example above shows that wildcard subpatterns are also usable
+in this property. See L<perlunicode/Wildcards in Property Values>.
+
+=head2 Improvement of C<POSIX::mblen()>, C<mbtowc>, and C<wctomb>
+
+The C<POSIX::mblen()>, C<mbtowc>, and C<wctomb> functions now
+work on shift state locales and are thread-safe on C99 and above
+compilers when executed on a platform that has locale thread-safety; the
+length parameters are now optional.
+
+These functions are always executed under the current C language locale.
+(See L<perllocale>.)  Most locales are stateless, but a few, notably the
+very rarely encountered ISO 2022, maintain a state between calls to
+these functions. Previously the state was cleared on every call, but
+now the state is not reset unless the appropriate parameter is C<undef>.
+
+On threaded perls, the C99 functions L<mbrlen(3)>, L<mbrtowc(3)>, and
+L<wcrtomb(3)>, when available, are substituted for the plain functions.
+This makes these functions thread-safe when executing on a locale
+thread-safe platform.
+
+The string length parameters in C<mblen> and C<mbtowc> are now optional;
+useful only if you wish to restrict the length parsed in the source
+string to less than the actual length.
+
+=head2 Alpha assertions are no longer experimental
+
+See L<perlre/(*pla:pattern)>, L<perlre/(*plb:pattern)>,
+L<perlre/(*nla:pattern)>>, and L<perlre/(*nlb:pattern)>.
+Use of these no longer generates a warning; existing code that disables
+the warning category C<experimental::alpha_assertions> will continue to work
+without any changes needed. Enabling the category has no effect.
+
+=head2 Script runs are no longer experimental
+
+See L<perlre/Script Runs>. Use of these no longer generates a warning;
+existing code that disables the warning category
+C<experimental::script_run> will continue to work without any
+changes needed. Enabling the category has no effect.
+
+=head2 Feature checks are now faster
+
+Previously feature checks in the parser required a hash lookup when
+features were set outside of a feature bundle, this has been optimized
+to a bit mask check. [L<GH #17229|https://github.com/Perl/perl5/issues/17229>]
+
+=head2 Perl is now developed on GitHub
+
+Perl is now developed on GitHub. You can find us at
+L<https://github.com/Perl/perl5>.
+
+Non-security bugs should now be reported via GitHub. Security issues should
+continue to be reported as documented in L<perlsec>.
+
+=head2 Compiled patterns can now be dumped before optimization
+
+This is primarily useful for tracking down bugs in the regular
+expression compiler. This dump happens on C<-DDEBUGGING> perls, if you
+specify C<-Drv> on the command line; or on any perl if the pattern is
+compiled within the scope of S<C<use re qw(Debug DUMP_PRE_OPTIMIZE)>> or
+S<C<use re qw(Debug COMPILE EXTRA)>>. (All but the second case display
+other information as well.)
+
+=head1 Security
+
+=head2 [CVE-2020-10543] Buffer overflow caused by a crafted regular expression
+
+A signed C<size_t> integer overflow in the storage space calculations for
+nested regular expression quantifiers could cause a heap buffer overflow in
+Perl's regular expression compiler that overwrites memory allocated after the
+regular expression storage space with attacker supplied data.
+
+The target system needs a sufficient amount of memory to allocate partial
+expansions of the nested quantifiers prior to the overflow occurring.  This
+requirement is unlikely to be met on 64-bit systems.
+
+Discovered by: ManhND of The Tarantula Team, VinCSS (a member of Vingroup).
+
+=head2 [CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression
+
+Integer overflows in the calculation of offsets between instructions for the
+regular expression engine could cause corruption of the intermediate language
+state of a compiled regular expression.  An attacker could abuse this behaviour
+to insert instructions into the compiled form of a Perl regular expression.
+
+Discovered by: Hugo van der Sanden and Slaven Rezic.
+
+=head2 [CVE-2020-12723] Buffer overflow caused by a crafted regular expression
+
+Recursive calls to C<S_study_chunk()> by Perl's regular expression compiler to
+optimize the intermediate language representation of a regular expression could
+cause corruption of the intermediate language state of a compiled regular
+expression.
+
+Discovered by: Sergey Aleynikov.
+
+=head2 Additional Note
+
+An application written in Perl would only be vulnerable to any of the above
+flaws if it evaluates regular expressions supplied by the attacker.  Evaluating
+regular expressions in this fashion is known to be dangerous since the regular
+expression engine does not protect against denial of service attacks in this
+usage scenario.
+
+=head1 Incompatible Changes
+
+=head2 Certain pattern matching features are now prohibited in compiling
+Unicode property value wildcard subpatterns
+
+These few features are either inappropriate or interfere with the
+algorithm used to accomplish this task. The complete list is in
+L<perlunicode/Wildcards in Property Values>.
+
+=head2 Unused functions C<POSIX::mbstowcs> and C<POSIX::wcstombs> are removed
+
+These functions could never have worked due to a defective interface
+specification. There is clearly no demand for them, given that no one
+has ever complained in the many years the functions were claimed to be
+available, hence so-called "support" for them is now dropped.
+
+=head2 A bug fix for C<(?[...])> may have caused some patterns to no
+longer compile
+
+See L</Selected Bug Fixes>. The heuristics previously used may have let
+some constructs compile (perhaps not with the programmer's intended
+effect) that should have been errors. None are known, but it is
+possible that some erroneous constructs no longer compile.
+
+=head2 C<\p{I<user-defined>}> properties now always override official
+Unicode ones
+
+Previously, if and only if a user-defined property was declared prior to
+the compilation of the regular expression pattern that contains it, its
+definition was used instead of any official Unicode property with the
+same name. Now, it always overrides the official property. This
+change could break existing code that relied (likely unwittingly) on the
+previous behavior. Without this fix, if Unicode released a new version
+with a new property that happens to have the same name as the one you
+had long been using, your program would break when you upgraded to a
+perl that used that new Unicode version. See L<perlunicode/User-Defined
+Character Properties>. [L<GH #17205|https://github.com/Perl/perl5/issues/17205>]
+
+=head2 Modifiable variables are no longer permitted in constants
+
+Code like:
+
+    my $var;
+    $sub = sub () { $var };
+
+where C<$var> is referenced elsewhere in some sort of modifiable context now
+produces an exception when the sub is defined.
+
+This error can be avoided by adding a return to the sub definition:
+
+    $sub = sub () { return $var };
+
+This has been deprecated since Perl 5.22.
+[L<perl #134138|https://rt.perl.org/Ticket/Display.html?id=134138>]
+
+=head2 Use of L<C<vec>|perlfunc/vec EXPR,OFFSET,BITS> on strings with code points above 0xFF is forbidden
+
+Such strings are represented internally in UTF-8, and C<vec> is a
+bit-oriented operation that will likely give unexpected results on those
+strings. This was deprecated in perl 5.28.0.
+
+=head2 Use of code points over 0xFF in string bitwise operators
+
+Some uses of these were already illegal after a previous deprecation
+cycle. The remaining uses are now prohibited, having been deprecated in perl
+5.28.0. See L<perldeprecation>.
+
+=head2 C<Sys::Hostname::hostname()> does not accept arguments
+
+This usage was deprecated in perl 5.28.0 and is now fatal.
+
+=head2 Plain "0" string now treated as a number for range operator
+
+Previously a range C<"0" .. "-1"> would produce a range of numeric
+strings from "0" through "99"; this now produces an empty list, just
+as C<0 .. -1> does. This also means that C<"0" .. "9"> now produces a
+list of integers, where previously it would produce a list of strings.
+
+This was due to a special case that treated strings starting with "0"
+as strings so ranges like C<"00" .. "03"> produced C<"00", "01", "02", "03">,
+but didn't specially handle the string C<"0">.
+[L<perl #133695|https://rt.perl.org/Ticket/Display.html?id=133695>]
+
+=head2 C<\K> now disallowed in look-ahead and look-behind assertions
+
+This was disallowed because it causes unexpected behaviour, and no-one
+could define what the desired behaviour should be.
+[L<perl #124256|https://rt.perl.org/Ticket/Display.html?id=124256>]
+
+=head1 Performance Enhancements
+
+=over 4
+
+=item *
+
+C<my_strnlen> has been sped up for systems that don't have their own
+C<strnlen> implementation.
+
+=item *
+
+C<grok_bin_oct_hex> (and so, C<grok_bin>, C<grok_oct>, and C<grok_hex>)
+have been sped up.
+
+=item *
+
+C<grok_number_flags> has been sped up.
+
+=item *
+
+C<sort> is now noticeably faster in cases such as C<< sort {$a <=> $b} >> or
+C<< sort {$b <=> $a} >>. [L<GH #17608|https://github.com/Perl/perl5/pull/17608>]
+
+=back
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Archive::Tar> has been upgraded from version 2.32 to 2.36.
+
+=item *
+
+L<autodie> has been upgraded from version 2.29 to 2.32.
+
+=item *
+
+L<B> has been upgraded from version 1.76 to 1.80.
+
+=item *
+
+L<B::Deparse> has been upgraded from version 1.49 to 1.54.
+
+=item *
+
+L<Benchmark> has been upgraded from version 1.22 to 1.23.
+
+=item *
+
+L<charnames> has been upgraded from version 1.45 to 1.48.
+
+=item *
+
+L<Class::Struct> has been upgraded from version 0.65 to 0.66.
+
+=item *
+
+L<Compress::Raw::Bzip2> has been upgraded from version 2.084 to 2.093.
+
+=item *
+
+L<Compress::Raw::Zlib> has been upgraded from version 2.084 to 2.093.
+
+=item *
+
+L<CPAN> has been upgraded from version 2.22 to 2.27.
+
+=item *
+
+L<DB_File> has been upgraded from version 1.843 to 1.853.
+
+=item *
+
+L<Devel::PPPort> has been upgraded from version 3.52 to 3.57.
+
+The test files generated on Win32 are now identical to when they are
+generated on POSIX-like systems.
+
+=item *
+
+L<diagnostics> has been upgraded from version 1.36 to 1.37.
+
+=item *
+
+L<Digest::MD5> has been upgraded from version 2.55 to 2.55_01.
+
+=item *
+
+L<Dumpvalue> has been upgraded from version 1.18 to 1.21.
+
+Previously, when dumping elements of an array and encountering an undefined
+value, the string printed would have been C<empty array>. This has been
+changed to what was apparently originally intended:  C<empty slot>.
+
+=item *
+
+L<DynaLoader> has been upgraded from version 1.45 to 1.47.
+
+=item *
+
+L<Encode> has been upgraded from version 3.01 to 3.06.
+
+=item *
+
+L<encoding> has been upgraded from version 2.22 to 3.00.
+
+=item *
+
+L<English> has been upgraded from version 1.10 to 1.11.
+
+=item *
+
+L<Exporter> has been upgraded from version 5.73 to 5.74.
+
+=item *
+
+L<ExtUtils::CBuilder> has been upgraded from version 0.280231 to 0.280234.
+
+=item *
+
+L<ExtUtils::MakeMaker> has been upgraded from version 7.34 to 7.44.
+
+=item *
+
+L<feature> has been upgraded from version 1.54 to 1.58.
+
+A new C<indirect> feature has been added, which is enabled by default
+but allows turning off L<indirect object syntax|perlobj/Indirect
+Object Syntax>.
+
+=item *
+
+L<File::Find> has been upgraded from version 1.36 to 1.37.
+
+On Win32, the tests no longer require either a file in the drive root
+directory, or a writable root directory.
+
+=item *
+
+L<File::Glob> has been upgraded from version 1.32 to 1.33.
+
+=item *
+
+L<File::stat> has been upgraded from version 1.08 to 1.09.
+
+=item *
+
+L<Filter::Simple> has been upgraded from version 0.95 to 0.96.
+
+=item *
+
+L<Getopt::Long> has been upgraded from version 2.5 to 2.51.
+
+=item *
+
+L<Hash::Util> has been upgraded from version 0.22 to 0.23.
+
+The Synopsis has been updated as the example code stopped working with
+newer perls.
+[L<GH #17399|https://github.com/Perl/perl5/issues/17399>]
+
+=item *
+
+L<I18N::Langinfo> has been upgraded from version 0.18 to 0.19.
+
+=item *
+
+L<I18N::LangTags> has been upgraded from version 0.43 to 0.44.
+
+Document the C<IGNORE_WIN32_LOCALE> environment variable.
+
+=item *
+
+L<IO> has been upgraded from version 1.40 to 1.43.
+
+L<IO::Socket> no longer caches a zero protocol value, since this
+indicates that the implementation will select a protocol. This means
+that on platforms that don't implement C<SO_PROTOCOL> for a given
+socket type the protocol method may return C<undef>.
+
+The supplied I<TO> is now always honoured on calls to the C<send()>
+method. [L<perl #133936|https://rt.perl.org/Ticket/Display.html?id=133936>]
+
+=item *
+
+IO-Compress has been upgraded from version 2.084 to 2.093.
+
+=item *
+
+L<IPC::Cmd> has been upgraded from version 1.02 to 1.04.
+
+=item *
+
+L<IPC::Open3> has been upgraded from version 1.20 to 1.21.
+
+=item *
+
+L<JSON::PP> has been upgraded from version 4.02 to 4.04.
+
+=item *
+
+L<Math::BigInt> has been upgraded from version 1.999816 to 1.999818.
+
+=item *
+
+L<Math::BigInt::FastCalc> has been upgraded from version 0.5008 to 0.5009.
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 5.20190522 to 5.20200620.
+
+=item *
+
+L<Module::Load::Conditional> has been upgraded from version 0.68 to 0.70.
+
+=item *
+
+L<Module::Metadata> has been upgraded from version 1.000036 to 1.000037.
+
+=item *
+
+L<mro> has been upgraded from version 1.22 to 1.23.
+
+=item *
+
+L<Net::Ping> has been upgraded from version 2.71 to 2.72.
+
+=item *
+
+L<Opcode> has been upgraded from version 1.43 to 1.47.
+
+=item *
+
+L<open> has been upgraded from version 1.11 to 1.12.
+
+=item *
+
+L<overload> has been upgraded from version 1.30 to 1.31.
+
+=item *
+
+L<parent> has been upgraded from version 0.237 to 0.238.
+
+=item *
+
+L<perlfaq> has been upgraded from version 5.20190126 to 5.20200523.
+
+=item *
+
+L<PerlIO> has been upgraded from version 1.10 to 1.11.
+
+=item *
+
+L<PerlIO::encoding> has been upgraded from version 0.27 to 0.28.
+
+=item *
+
+L<PerlIO::via> has been upgraded from version 0.17 to 0.18.
+
+=item *
+
+L<Pod::Html> has been upgraded from version 1.24 to 1.25.
+
+=item *
+
+L<Pod::Simple> has been upgraded from version 3.35 to 3.40.
+
+=item *
+
+L<podlators> has been upgraded from version 4.11 to 4.14.
+
+=item *
+
+L<POSIX> has been upgraded from version 1.88 to 1.94.
+
+=item *
+
+L<re> has been upgraded from version 0.37 to 0.40.
+
+=item *
+
+L<Safe> has been upgraded from version 2.40 to 2.41.
+
+=item *
+
+L<Scalar::Util> has been upgraded from version 1.50 to 1.55.
+
+=item *
+
+L<SelfLoader> has been upgraded from version 1.25 to 1.26.
+
+=item *
+
+L<Socket> has been upgraded from version 2.027 to 2.029.
+
+=item *
+
+L<Storable> has been upgraded from version 3.15 to 3.21.
+
+Use of C<note()> from L<Test::More> is now optional in tests. This works
+around a circular dependency with L<Test::More> when installing on very
+old perls from CPAN.
+
+Vstring magic strings over 2GB are now disallowed.
+
+Regular expressions objects weren't properly counted for object id
+purposes on retrieve. This would corrupt the resulting structure, or
+cause a runtime error in some cases. [L<perl #134179|https://rt.perl.org/Ticket/Display.html?id=134179>]
+
+=item *
+
+L<Sys::Hostname> has been upgraded from version 1.22 to 1.23.
+
+=item *
+
+L<Sys::Syslog> has been upgraded from version 0.35 to 0.36.
+
+=item *
+
+L<Term::ANSIColor> has been upgraded from version 4.06 to 5.01.
+
+=item *
+
+L<Test::Simple> has been upgraded from version 1.302162 to 1.302175.
+
+=item *
+
+L<Thread> has been upgraded from version 3.04 to 3.05.
+
+=item *
+
+L<Thread::Queue> has been upgraded from version 3.13 to 3.14.
+
+=item *
+
+L<threads> has been upgraded from version 2.22 to 2.25.
+
+=item *
+
+L<threads::shared> has been upgraded from version 1.60 to 1.61.
+
+=item *
+
+L<Tie::File> has been upgraded from version 1.02 to 1.06.
+
+=item *
+
+L<Tie::Hash::NamedCapture> has been upgraded from version 0.10 to 0.13.
+
+=item *
+
+L<Tie::Scalar> has been upgraded from version 1.04 to 1.05.
+
+=item *
+
+L<Tie::StdHandle> has been upgraded from version 4.5 to 4.6.
+
+=item *
+
+L<Time::HiRes> has been upgraded from version 1.9760 to 1.9764.
+
+Removed obsolete code such as support for pre-5.6 perl and classic
+MacOS. [L<perl #134288|https://rt.perl.org/Ticket/Display.html?id=134288>]
+
+=item *
+
+L<Time::Piece> has been upgraded from version 1.33 to 1.3401.
+
+=item *
+
+L<Unicode::Normalize> has been upgraded from version 1.26 to 1.27.
+
+=item *
+
+L<Unicode::UCD> has been upgraded from version 0.72 to 0.75.
+
+=item *
+
+L<VMS::Stdio> has been upgraded from version 2.44 to 2.45.
+
+=item *
+
+L<warnings> has been upgraded from version 1.44 to 1.47.
+
+=item *
+
+L<Win32> has been upgraded from version 0.52 to 0.53.
+
+=item *
+
+L<Win32API::File> has been upgraded from version 0.1203 to 0.1203_01.
+
+=item *
+
+L<XS::APItest> has been upgraded from version 1.00 to 1.09.
+
+=back
+
+=head2 Removed Modules and Pragmata
+
+=over 4
+
+=item *
+
+Pod::Parser has been removed from the core distribution.
+It still is available for download from CPAN. This resolves [L<perl
+#119439|https://rt.perl.org/Ticket/Display.html?id=119439>].
+
+=back
+
+=head1 Documentation
+
+=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, open an issue
+at L<https://github.com/Perl/perl5/issues>.
+
+Additionally, the following selected changes have been made:
+
+=head3 L<perldebguts>
+
+=over 4
+
+=item *
+
+Simplify a few regnode definitions
+
+Update C<BOUND> and C<NBOUND> definitions.
+
+=item *
+
+Add ANYOFHs regnode
+
+This node is like C<ANYOFHb>, but is used when more than one leading byte
+is the same in all the matched code points.
+
+C<ANYOFHb> is used to avoid having to convert from UTF-8 to code point for
+something that won't match. It checks that the first byte in the UTF-8
+encoded target is the desired one, thus ruling out most of the possible
+code points.
+
+=back
+
+=head3 L<perlapi>
+
+=over 4
+
+=item *
+
+C<sv_2pvbyte> updated to mention it will croak if the SV cannot be
+downgraded.
+
+=item *
+
+C<sv_setpvn> updated to mention that the UTF-8 flag will not be changed by
+this function, and a terminating NUL byte is guaranteed.
+
+=item *
+
+Documentation for C<PL_phase> has been added.
+
+=item *
+
+The documentation for C<grok_bin>, C<grok_oct>, and C<grok_hex> has been
+updated and clarified.
+
+=back
+
+=head3 L<perldiag>
+
+=over 4
+
+=item *
+
+Add documentation for experimental 'isa' operator
+
+(S experimental::isa) This warning is emitted if you use the (C<isa>)
+operator. This operator is currently experimental and its behaviour may
+change in future releases of Perl.
+
+=back
+
+=head3 L<perlfunc>
+
+=over 4
+
+=item C<caller>
+
+Like L<C<__FILE__>|/__FILE__> and L<C<__LINE__>|/__LINE__>, the filename and
+line number returned here may be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
+
+=item C<__FILE__>
+
+It can be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
+
+=item C<__LINE__>
+
+It can be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
+
+=item C<return>
+
+Now mentions that you cannot return from C<do BLOCK>.
+
+=item C<open>
+
+The C<open()> section had been renovated significantly.
+
+=back
+
+=head3 L<perlguts>
+
+=over 4
+
+=item *
+
+No longer suggesting using perl's C<malloc>. Modern system C<malloc> is
+assumed to be much better than perl's implementation now.
+
+=item *
+
+Documentation about F<embed.fnc> flags has been removed. F<embed.fnc> now has
+sufficient comments within it. Anyone changing that file will see those
+comments first, so entries here are now redundant.
+
+=item *
+
+Updated documentation for C<UTF8f>
+
+=item *
+
+Added missing C<=for apidoc> lines
+
+=back
+
+=head3 L<perlhacktips>
+
+=over 4
+
+=item *
+
+The differences between Perl strings and C strings are now detailed.
+
+=back
+
+=head3 L<perlintro>
+
+=over 4
+
+=item *
+
+The documentation for the repetition operator C<x> have been clarified.
+[L<GH #17335|https://github.com/Perl/perl5/issues/17335>]
+
+=back
+
+=head3 L<perlipc>
+
+=over 4
+
+=item *
+
+The documentation surrounding C<open> and handle usage has been modernized
+to prefer 3-arg open and lexical variables instead of barewords.
+
+=item *
+
+Various updates and fixes including making all examples strict-safe and
+replacing C<-w> with C<use warnings>.
+
+=back
+
+=head3 L<perlop>
+
+=over 4
+
+=item *
+
+'isa' operator is experimental
+
+This is an experimental feature and is available when enabled
+by C<use feature 'isa'>. It emits a warning in the C<experimental::isa>
+category.
+
+=back
+
+=head3 L<perlpod>
+
+=over 4
+
+=item *
+
+Details of the various stacks within the perl interpreter are now explained
+here.
+
+=item *
+
+Advice has been added regarding the usage of C<< ZE<lt>E<gt> >>.
+
+=back
+
+=head3 L<perlport>
+
+=over 4
+
+=item *
+
+Update C<timegm> example to use the correct year format I<1970> instead of I<70>.
+[L<GH #16431|https://github.com/Perl/perl5/issues/16431>]
+
+=back
+
+=head3 L<perlreref>
+
+=over 4
+
+=item *
+
+Fix some typos.
+
+=back
+
+=head3 L<perlvar>
+
+=over 4
+
+=item *
+
+Now recommends stringifying C<$]> and comparing it numerically.
+
+=back
+
+=head3 L<perlapi>, L<perlintern>
+
+=over 4
+
+=item *
+
+Documentation has been added for several functions that were
+lacking it before.
+
+=back
+
+=head3 L<perlxs>
+
+=over 4
+
+=item *
+
+Suggest using C<libffi> for simple library bindings via CPAN modules
+like L<FFI::Platypus> or L<FFI::Raw>.
+
+=back
+
+=head3 L<POSIX>
+
+=over 4
+
+=item *
+
+C<setlocale> warning about threaded builds updated to note it does not
+apply on Perl 5.28.X and later.
+
+=item *
+
+C<< Posix::SigSet->new(...) >> updated to state it throws an error if any of
+the supplied signals cannot be added to the set.
+
+=back
+
+Additionally, the following selected changes have been made:
+
+=head3 Updating of links
+
+=over 4
+
+=item *
+
+Links to the now defunct L<https://search.cpan.org> site now point at
+the equivalent L<https://metacpan.org> URL. [L<GH #17393|https://github.com/Perl/perl5/issues/17393>]
+
+=item *
+
+The man page for L<ExtUtils::XSSymSet> is now only installed on VMS,
+which is the only platform the module is installed on. [L<GH #17424|https://github.com/Perl/perl5/issues/17424>]
+
+=item *
+
+URLs have been changed to C<https://> and stale links have been updated.
+
+Where applicable, the URLs in the documentation have been moved from using the
+C<http://> protocol to C<https://>. This also affects the location of the bug
+tracker at L<https://rt.perl.org>.
+
+=item *
+
+Some links to OS/2 libraries, Address Sanitizer and other system tools had gone
+stale. These have been updated with working links.
+
+=item *
+
+Some links to old email addresses on perl5-porters had gone stale. These have been
+updated with working links.
+
+=back
+
+=head1 Diagnostics
+
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages. For the complete list of
+diagnostic messages, see L<perldiag>.
+
+=head2 New Diagnostics
+
+=head3 New Errors
+
+=over 4
+
+=item *
+
+L<Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>
+|perldiag/"Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>">
+
+This is a replacement for several error messages listed under
+L</Changes to Existing Diagnostics>.
+
+=item *
+
+C<L<No digits found for %s literal|perldiag/"No digits found for %s literal">>
+
+(F) No hexadecimal digits were found following C<0x> or no binary digits were
+found following C<0b>.
+
+=back
+
+=head3 New Warnings
+
+=over 4
+
+=item *
+
+L<Code point 0x%X is not Unicode, and not portable|perldiag/"Code point 0x%X is not Unicode, and not portable">
+
+This is actually not a new message, but it is now output when the
+warnings category C<portable> is enabled.
+
+When raised during regular expression pattern compilation, the warning
+has extra text added at the end marking where precisely in the pattern
+it occurred.
+
+=item *
+
+L<Non-hex character '%c' terminates \x early.  Resolved as "%s"|perldiag/"Non-hex character '%c' terminates \x early.  Resolved as "%s"">
+
+This replaces a warning that was much less specific, and which gave
+false information. This new warning parallels the similar
+already-existing one raised for C<\o{}>.
+
+=back
+
+=head2 Changes to Existing Diagnostics
+
+=over 4
+
+=item *
+
+L<Character following "\c" must be printable ASCII|perldiag/"Character following "\c" must be printable ASCII">
+
+...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+
+=item *
+
+L<Use "%s" instead of "%s"|perldiag/"Use "%s" instead of "%s"">
+
+...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+
+=item *
+
+L<Sequence "\c{" invalid|perldiag/"Sequence "\c{" invalid">
+
+...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+
+=item *
+
+L<"\c%c" is more clearly written simply as "%s"|perldiag/""\c%c" is more clearly written simply as "%s"">
+
+...now has extra text added at the end, when raised during regular
+expression pattern compilation, marking where precisely in the pattern
+it occurred.
+
+=item *
+
+L<Non-octal character '%c' terminates \o early.  Resolved as "%s"|perldiag/"Non-octal character '%c' terminates \o early.  Resolved as "%s"">
+
+...now includes the phrase "terminates \o early", and has extra text added
+at the end, when raised during regular expression pattern compilation,
+marking where precisely in the pattern it occurred. In some instances
+the text of the resolution has been clarified.
+
+=item *
+
+L<'%s' resolved to '\o{%s}%d'|perldiag/'%s' resolved to '\o{%s}%d'>
+
+As of Perl 5.32, this message is no longer generated. Instead,
+L<perldiag/Non-octal character '%c' terminates \o early.  Resolved as "%s">
+is used instead.
+
+=item *
+
+L<Use of code point 0x%s is not allowed; the permissible max is 0x%X|perldiag/"Use of code point 0x%s is not allowed; the permissible max is 0x%X">
+
+Some instances of this message previously output the hex digits C<A>,
+C<B>, C<C>, C<D>, C<E>, and C<F> in lower case. Now they are all
+consistently upper case.
+
+=item *
+
+The following three diagnostics have been removed, and replaced by
+L<C<Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>>
+|perldiag/"Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>">:
+C<Expecting close paren for nested extended charclass in regex; marked
+by <-- HERE in mE<sol>%sE<sol>>,
+C<Expecting close paren for wrapper for nested extended charclass in
+regex; marked by <-- HERE in mE<sol>%sE<sol>>,
+and
+C<Expecting '(?flags:(?[...' in regex; marked by S<<-- HERE> in mE<sol>%sE<sol>>.
+
+=item *
+
+The C<Code point 0x%X is not Unicode, and not portable> warning removed
+the line C<Code points above 0xFFFF_FFFF require larger than a 32 bit word.>
+as code points that large are no longer legal on 32-bit platforms.
+
+=item *
+
+L<Can't use global %s in %s|perldiag/"Can't use global %s in %s">
+
+This error message has been slightly reformatted from the original C<Can't use
+global %s in "%s">, and in particular misleading error messages like C<Can't
+use global $_ in "my"> are now rendered as C<Can't use global $_ in subroutine
+signature>.
+
+=item *
+
+L<Constants from lexical variables potentially modified elsewhere are no longer permitted|perldiag/"Constants from lexical variables potentially modified elsewhere are no longer permitted">
+
+This error message replaces the former C<Constants from lexical variables
+potentially modified elsewhere are deprecated. This will not be allowed in Perl
+5.32> to reflect the fact that this previously deprecated usage has now been
+transformed into an exception. The message's classification has also been
+updated from D (deprecated) to F (fatal).
+
+See also L</Incompatible Changes>.
+
+=item *
+
+C<\N{} here is restricted to one character> is now emitted in the same
+circumstances where previously C<\N{} in inverted character class or as a range
+end-point is restricted to one character> was.
+
+This is due to new circumstances having been added in Perl 5.30 that weren't
+covered by the earlier wording.
+
+=back
+
+=head1 Utility Changes
+
+=head2 L<perlbug>
+
+=over 4
+
+=item * The bug tracker homepage URL now points to GitHub.
+
+=back
+
+=head2 L<streamzip>
+
+=over 4
+
+=item *
+
+This is a new utility, included as part of an
+L<IO::Compress::Base> upgrade.
+
+L<streamzip> creates a zip file from stdin. The program will read data
+from stdin, compress it into a zip container and, by default, write a
+streamed zip file to stdout.
+
+=back
+
+=head1 Configuration and Compilation
+
+=head2 F<Configure>
+
+=over 4
+
+=item *
+
+For clang++, add C<< #include <stdlib.h> >> to Configure's probes for
+C<futimes>, C<strtoll>, C<strtoul>, C<strtoull>, C<strtouq>, otherwise the
+probes would fail to compile.
+
+=item *
+
+Use a compile and run test for C<lchown> to satisfy clang++ which should
+more reliably detect it.
+
+=item *
+
+For C++ compilers, add C<< #include <stdio.h> >> to Configure's probes for
+C<getpgrp> and C<setpgrp> as they use printf and C++ compilers may fail
+compilation instead of just warning.
+
+=item *
+
+Check if the compiler can handle inline attribute.
+
+=item *
+
+Check for character data alignment.
+
+=item *
+
+F<Configure> now correctly handles gcc-10. Previously it was interpreting it
+as gcc-1 and turned on C<-fpcc-struct-return>.
+
+=item *
+
+Perl now no longer probes for C<d_u32align>, defaulting to C<define> on all
+platforms. This check was error-prone when it was done, which was on 32-bit
+platforms only.
+[L<perl #133495|https://rt.perl.org/Ticket/Display.html?id=133495>]
+
+=item *
+
+Documentation and hints for building perl on Z/OS (native EBCDIC) have been
+updated. This is still a work in progress.
+
+=item *
+
+A new probe for C<malloc_usable_size> has been added.
+
+=item *
+
+Improvements in F<Configure> to detection in C++ and clang++. Work ongoing by
+Andy Dougherty. [L<perl #134171|https://rt.perl.org/Ticket/Display.html?id=134171>]
+
+=item *
+
+F<autodoc.pl>
+
+This tool that regenerates L<perlintern> and L<perlapi> has been overhauled
+significantly, restoring consistency in flags used in F<embed.fnc> and
+L<Devel::PPPort> and allowing removal of many redundant C<=for apidoc>
+entries in code.
+
+=item *
+
+The C<ECHO> macro is now defined. This is used in a C<dtrace> rule that was
+originally changed for FreeBSD, and the FreeBSD make apparently predefines it.
+The Solaris make does not predefine C<ECHO> which broke this rule on Solaris.
+[L<perl #134218|https://rt.perl.org/Ticket/Display.html?id=134218>]
+
+=item *
+
+Bison versions 3.1 through 3.4 are now supported.
+
+=back
+
+=head1 Testing
+
+Tests were added and changed to reflect the other additions and
+changes in this release. Furthermore, these significant changes were
+made:
+
+=over 4
+
+=item *
+
+F<t/run/switches.t> no longer uses (and re-uses) the F<tmpinplace/>
+directory under F<t/>. This may prevent spurious failures. [L<GH #17424|https://github.com/Perl/perl5/issues/17424>]
+
+=item *
+
+Various bugs in C<POSIX::mbtowc> were fixed. Potential races with
+other threads are now avoided, and previously the returned wide
+character could well be garbage.
+
+=item *
+
+Various bugs in C<POSIX::wctomb> were fixed. Potential races with other
+threads are now avoided, and previously it would segfault if the string
+parameter was shared or hadn't been pre-allocated with a string of
+sufficient length to hold the result.
+
+=item *
+
+Certain test output of scalars containing control characters and Unicode
+has been fixed on EBCDIC.
+
+=item *
+
+F<t/charset_tools.pl>: Avoid some work on ASCII platforms.
+
+=item *
+
+F<t/re/regexp.t>: Speed up many regex tests on ASCII platform
+
+=item *
+
+F<t/re/pat.t>: Skip tests that don't work on EBCDIC.
+
+=back
+
+=head1 Platform Support
+
+=head2 Discontinued Platforms
+
+=over 4
+
+=item Windows CE
+
+Support for building perl on Windows CE has now been removed.
+
+=back
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item Linux
+
+C<cc> will be used to populate C<plibpth> if C<cc> is C<clang>.
+[L<perl #134189|https://rt.perl.org/Ticket/Display.html?id=134189>]
+
+=item NetBSD 8.0
+
+Fix compilation of Perl on NetBSD 8.0 with g++.
+[L<GH #17381|https://github.com/Perl/perl5/issues/17381>]
+
+=item Windows
+
+=over 4
+
+=item *
+
+The configuration for C<ccflags> and C<optimize> are now separate, as
+with POSIX platforms. [L<GH #17156|https://github.com/Perl/perl5/issues/17156>]
+
+=item *
+
+Support for building perl with Visual C++ 6.0 has now been removed.
+
+=item *
+
+The locale tests could crash on Win32 due to a Windows bug, and
+separately due to the CRT throwing an exception if the locale name
+wasn't validly encoded in the current code page.
+
+For the second we now decode the locale name ourselves, and always
+decode it as UTF-8. [L<perl #133981|https://rt.perl.org/Ticket/Display.html?id=133981>]
+
+=item *
+
+F<t/op/magic.t> could fail if environment variables starting with
+C<FOO> already existed.
+
+=item *
+
+MYMALLOC (PERL_MALLOC) build has been fixed.
+
+=back
+
+=item Solaris
+
+=over 4
+
+=item *
+
+C<Configure> will now find recent versions of the Oracle Developer Studio
+compiler, which are found under C</opt/developerstudio*>.
+
+=item *
+
+C<Configure> now uses the detected types for C<gethostby*> functions, allowing
+Perl to once again compile on certain configurations of Solaris.
+
+=back
+
+=item VMS
+
+=over 4
+
+=item *
+
+With the release of the patch kit C99 V2.0, VSI has provided support for a
+number of previously-missing C99 features. On systems with that patch kit
+installed, Perl's configuration process will now detect the presence of the
+header C<stdint.h> and the following functions: C<fpclassify>, C<isblank>, C<isless>,
+C<llrint>, C<llrintl>, C<llround>, C<llroundl>, C<nearbyint>, C<round>, C<scalbn>,
+and C<scalbnl>.
+
+=item *
+
+C<-Duse64bitint> is now the default on VMS.
+
+=back
+
+=item z/OS
+
+Perl 5.32 has been tested on z/OS 2.4, with the following caveats:
+
+=over 4
+
+=item *
+
+Only static builds (the default) build reliably
+
+=item *
+
+When using locales, z/OS does not handle the C<LC_MESSAGES> category
+properly, so when compiling perl, you should add the following to your
+F<Configure> options
+
+ ./Configure <other options> -Accflags=-DNO_LOCALE_MESSAGES
+
+=item *
+
+z/OS does not support locales with threads, so when compiling a threaded
+perl, you should add the following to your F<Configure> options
+
+ ./Configure <other Configure options> -Accflags=-DNO_LOCALE
+
+=item *
+
+Some CPAN modules that are shipped with perl fail at least one of their
+self-tests.  These are:
+Archive::Tar,
+Config::Perl::V,
+CPAN::Meta,
+CPAN::Meta::YAML,
+Digest::MD5,
+Digest::SHA,
+Encode,
+ExtUtils::MakeMaker,
+ExtUtils::Manifest,
+HTTP::Tiny,
+IO::Compress,
+IPC::Cmd,
+JSON::PP,
+libnet,
+MIME::Base64,
+Module::Metadata,
+PerlIO::via-QuotedPrint,
+Pod::Checker,
+podlators,
+Pod::Simple,
+Socket,
+and Test::Harness.
+
+The causes of the failures range from the self-test itself is flawed,
+and the module actually works fine, up to the module doesn't work at all
+on EBCDIC platforms.
+
+=back
+
+=back
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+C<savepvn>'s len parameter is now a C<Size_t> instead of an C<I32> since we
+can handle longer strings than 31 bits.
+
+=item *
+
+The lexer (C<Perl_yylex()> in F<toke.c>) was previously a single 4100-line
+function, relying heavily on C<goto> and a lot of widely-scoped local variables
+to do its work. It has now been pulled apart into a few dozen smaller static
+functions; the largest remaining chunk (C<yyl_word_or_keyword()>) is a little
+over 900 lines, and consists of a single C<switch> statement, all of whose
+C<case> groups are independent. This should be much easier to understand and
+maintain.
+
+=item *
+
+The OS-level signal handlers and type (Sighandler_t) used by the perl core
+were declared as having three parameters, but the OS was always told to
+call them with one argument. This has been fixed by declaring them to have
+one parameter. See the merge commit C<v5.31.5-346-g116e19abbf> for full
+details.
+
+=item *
+
+The code that handles C<tr///> has been extensively revised, fixing
+various bugs, especially when the source and/or replacement strings
+contain characters whose code points are above 255. Some of the bugs
+were undocumented, one being that under some circumstances (but not all)
+with C</s>, the squeezing was done based on the source, rather than the
+replacement. A documented bug that got fixed was
+[L<perl #125493|https://rt.perl.org/Ticket/Display.html?id=125493>].
+
+=item *
+
+A new macro for XS writers dealing with UTF-8-encoded Unicode strings
+has been created L<perlapi/C<UTF8_CHK_SKIP>> that is safer in the face
+of malformed UTF-8 input than L<perlapi/C<UTF8_SKIP>> (but not as safe
+as L<perlapi/C<UTF8_SAFE_SKIP>>). It won't read past a NUL character.
+It has been backported in L<Devel::PPPort> 3.55 and later.
+
+=item *
+
+Added the C<< PL_curstackinfo->si_cxsubix >> field. This records the stack index
+of the most recently pushed sub/format/eval context. It is set and restored
+automatically by C<cx_pushsub()>, C<cx_popsub()> etc., but would need to be
+manually managed if you do any unusual manipulation of the context stack.
+
+=item *
+
+Various macros dealing with character type classification and changing case
+where the input is encoded in UTF-8 now require an extra parameter to prevent
+potential reads beyond the end of the buffer. Use of these has generated a
+deprecation warning since Perl 5.26. Details are in
+L<perldeprecation/In XS code, use of various macros dealing with UTF-8.>
+
+=item *
+
+A new parser function L<parse_subsignature()|perlapi/parse_subsignature>
+allows a keyword plugin to parse a subroutine signature while C<use feature
+'signatures'> is in effect. This allows custom keywords to implement
+semantics similar to regular C<sub> declarations that include signatures.
+[L<perl #132474|https://rt.perl.org/Ticket/Display.html?id=132474>]
+
+=item *
+
+Since on some platforms we need to hold a mutex when temporarily
+switching locales, new macros (C<STORE_LC_NUMERIC_SET_TO_NEEDED_IN>,
+C<WITH_LC_NUMERIC_SET_TO_NEEDED> and C<WITH_LC_NUMERIC_SET_TO_NEEDED_IN>)
+have been added to make it easier to do this safely and efficiently
+as part of [L<perl #134172|https://rt.perl.org/Ticket/Display.html?id=134172>].
+
+=item *
+
+The memory bookkeeping overhead for allocating an OP structure has been
+reduced by 8 bytes per OP on 64-bit systems.
+
+=item *
+
+L<eval_pv()|perlapi/eval_pv> no longer stringifies the exception when
+C<croak_on_error> is true. [L<perl #134175|https://rt.perl.org/Ticket/Display.html?id=134175>]
+
+=item *
+
+The PERL_DESTRUCT_LEVEL environment variable was formerly only honoured on perl
+binaries built with DEBUGGING support. It is now checked on all perl builds.
+Its normal use is to force perl to individually free every block of memory
+which it has allocated before exiting, which is useful when using automated
+leak detection tools such as valgrind.
+
+=item *
+
+The API eval_sv() now accepts a C<G_RETHROW> flag. If this flag is set and an
+exception is thrown while compiling or executing the supplied code, it will be
+rethrown, and eval_sv() will not return.
+[L<perl #134177|https://rt.perl.org/Ticket/Display.html?id=134177>]
+
+=item *
+
+As part of the fix for
+[L<perl #2754|https://rt.perl.org/Ticket/Display.html?id=2754>] perl_parse()
+now returns non-zero if exit(0) is called in a C<BEGIN>, C<UNITCHECK> or
+C<CHECK> block.
+
+=item *
+
+Most functions which recursively walked an op tree during compilation have been
+made non-recursive. This avoids SEGVs from stack overflow when the op tree is
+deeply nested, such as C<$n == 1 ? "one" : $n == 2 ? "two" : ....> (especially
+in code which is auto-generated).
+
+This is particularly noticeable where the code is compiled within a separate
+thread, as threads tend to have small stacks by default.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+Previously L<perlfunc/require> would only treat the special built-in
+SV C<&PL_sv_undef> as a value in C<%INC> as if a previous C<require>
+has failed, treating other undefined SVs as if the previous C<require>
+has succeeded. This could cause unexpected success from C<require>
+e.g., on C<local %INC = %INC;>. This has been fixed. [L<GH #17428|https://github.com/Perl/perl5/issues/17428>]
+
+=item *
+
+C<(?{...})> eval groups in regular expressions no longer unintentionally
+trigger "EVAL without pos change exceeded limit in regex" [L<GH #17490|https://github.com/Perl/perl5/issues/17490>].
+
+=item *
+
+C<(?[...])> extended bracketed character classes do not wrongly raise an
+error on some cases where a previously-compiled such class is
+interpolated into another. The heuristics previously used have been
+replaced by a reliable method, and hence the diagnostics generated have
+changed. See L</Diagnostics>.
+
+=item *
+
+The debug display (say by specifying C<-Dr> or S<C<use re>> (with
+appropriate options) of compiled Unicode property wildcard subpatterns no
+longer has extraneous output.
+
+=item *
+
+Fix an assertion failure in the regular expression engine.
+[L<GH #17372|https://github.com/Perl/perl5/issues/17372>]
+
+=item *
+
+Fix coredump in pp_hot.c after C<B::UNOP_AUX::aux_list()>.
+[L<GH #17301|https://github.com/Perl/perl5/issues/17301>]
+
+=item *
+
+Loading IO is now threadsafe.
+[L<GH #14816|https://github.com/Perl/perl5/issues/14816>]
+
+=item *
+
+C<\p{user-defined}> overrides official Unicode [L<GH #17025|https://github.com/Perl/perl5/issues/17025>]
+
+Prior to this patch, the override was only sometimes in effect.
+
+=item *
+
+Properly handle filled C</il> regnodes and multi-char folds
+
+=item *
+
+Compilation error during make minitest [L<GH #17293|https://github.com/Perl/perl5/issues/17293>]
+
+=item *
+
+Move the implementation of C<%->, C<%+> into core.
+
+=item *
+
+Read beyond buffer in C<grok_inf_nan> [L<GH #17370|https://github.com/Perl/perl5/issues/17370>]
+
+=item *
+
+Workaround glibc bug with C<LC_MESSAGES> [L<GH #17081|https://github.com/Perl/perl5/issues/17081>]
+
+=item *
+
+C<printf()> or C<sprintf()> with the C<%n> format could cause a panic on
+debugging builds, or report an incorrectly cached length value when
+producing C<SVfUTF8> flagged strings. [L<GH #17221|https://github.com/Perl/perl5/issues/17221>]
+
+=item *
+
+The tokenizer has been extensively refactored.
+[L<GH #17241|https://github.com/Perl/perl5/issues/17241>]
+[L<GH #17189|https://github.com/Perl/perl5/issues/17189>]
+
+=item *
+
+C<use strict "subs"> is now enforced for bareword constants optimized
+into a C<multiconcat> operator. [L<GH #17254|https://github.com/Perl/perl5/issues/17254>]
+
+=item *
+
+A memory leak in regular expression patterns has been fixed. [L<GH #17218|https://github.com/Perl/perl5/issues/17218>]
+
+=item *
+
+Perl no longer treats strings starting with "0x" or "0b" as hex or
+binary numbers respectively when converting a string to a number.
+This reverts a change in behaviour inadvertently introduced in perl
+5.30.0 intended to improve precision when converting a string to a
+floating point number. [L<perl #134230|https://rt.perl.org/Ticket/Display.html?id=134230>]
+
+=item *
+
+Matching a non-C<SVf_UTF8> string against a regular expression
+containing unicode literals could leak a SV on each match attempt.
+[L<perl #134390|https://rt.perl.org/Ticket/Display.html?id=134390>]
+
+=item *
+
+Overloads for octal and binary floating point literals were always
+passed a string with a C<0x> prefix instead of the appropriate C<0> or
+C<0b> prefix. [L<perl #125557|https://rt.perl.org/Ticket/Display.html?id=125557>]
+
+=item *
+
+C<< $@ = 100; die; >> now correctly propagates the 100 as an exception
+instead of ignoring it. [L<perl #134291|https://rt.perl.org/Ticket/Display.html?id=134291>]
+
+=item *
+
+C<< 0 0x@ >> no longer asserts in S_no_op(). [L<perl #134310|https://rt.perl.org/Ticket/Display.html?id=134310>]
+
+=item *
+
+Exceptions thrown while C<$@> is read-only could result in infinite
+recursion as perl tried to update C<$@>, which throws another
+exception, resulting in a stack overflow. Perl now replaces C<$@>
+with a copy if it's not a simple writable SV. [L<perl #134266|https://rt.perl.org/Ticket/Display.html?id=134266>]
+
+=item *
+
+Setting C<$)> now properly sets supplementary group ids if you have
+the necessary privileges. [L<perl #134169|https://rt.perl.org/Ticket/Display.html?id=134169>]
+
+=item *
+
+close() on a pipe now preemptively clears the PerlIO object from the
+IO SV. This prevents a second attempt to close the already closed
+PerlIO object if a signal handler calls die() or exit() while close()
+is waiting for the child process to complete. [L<perl #122112|https://rt.perl.org/Ticket/Display.html?id=122112>]
+
+=item *
+
+C<< sprintf("%.*a", -10000, $x) >> would cause a buffer overflow due
+to mishandling of the negative precision value. [L<perl #134008|https://rt.perl.org/Ticket/Display.html?id=134008>]
+
+=item *
+
+scalar() on a reference could cause an erroneous assertion failure
+during compilation. [L<perl #134045|https://rt.perl.org/Ticket/Display.html?id=134045>]
+
+=item *
+
+C<%{^CAPTURE_ALL}> is now an alias to C<%-> as documented, rather than
+incorrectly an alias for C<%+>. [L<perl #131867|https://rt.perl.org/Ticket/Display.html?id=131867>]
+
+=item *
+
+C<%{^CAPTURE}> didn't work if C<@{^CAPTURE}> was mentioned first.
+Similarly for C<%{^CAPTURE_ALL}> and C<@{^CAPTURE_ALL}>, though
+C<@{^CAPTURE_ALL}> currently isn't used. [L<perl #134193|https://rt.perl.org/Ticket/Display.html?id=134193>]
+
+=item *
+
+Extraordinarily large (over 2GB) floating point format widths could
+cause an integer overflow in the underlying call to snprintf(),
+resulting in an assertion. Formatted floating point widths are now
+limited to the range of int, the return value of snprintf(). [L<perl
+#133913|https://rt.perl.org/Ticket/Display.html?id=133913>]
+
+=item *
+
+Parsing the following constructs within a sub-parse (such as with
+C<"${code here}"> or C<s/.../code here/e>) has changed to match how
+they're parsed normally:
+
+=over
+
+=item *
+
+C<print $fh ...> no longer produces a syntax error.
+
+=item *
+
+Code like C<s/.../ ${time} /e> now properly produces an "Ambiguous use
+of ${time} resolved to $time at ..." warning when warnings are enabled.
+
+=item *
+
+C<@x {"a"}> (with the space) in a sub-parse now properly produces a
+"better written as" warning when warnings are enabled.
+
+=item *
+
+Attributes can now be used in a sub-parse.
+[L<perl #133850|https://rt.perl.org/Ticket/Display.html?id=133850>]
+
+=back
+
+=item *
+
+Incomplete hex and binary literals like C<0x> and C<0b> are now
+treated as if the C<x> or C<b> is part of the next token. [L<perl
+#134125|https://rt.perl.org/Ticket/Display.html?id=134125>]
+
+=item *
+
+A spurious C<)> in a subparse, such as in C<s/.../code here/e> or
+C<"...${code here}">, no longer confuses the parser.
+
+Previously a subparse was bracketed with generated C<(> and C<)>
+tokens, so a spurious C<)> would close the construct without doing the
+normal subparse clean up, confusing the parser and possible causing an
+assertion failure.
+
+Such constructs are now surrounded by artificial tokens that can't be
+included in the source. [L<perl #130585|https://rt.perl.org/Ticket/Display.html?id=130585>]
+
+=item *
+
+Reference assignment of a sub, such as C<\&foo = \&bar;>, silently did
+nothing in the C<main::> package. [L<perl #134072|https://rt.perl.org/Ticket/Display.html?id=134072>]
+
+=item *
+
+sv_gets() now recovers better if the target SV is modified by a signal
+handler. [L<perl #134035|https://rt.perl.org/Ticket/Display.html?id=134035>]
+
+=item *
+
+C<readline @foo> now evaluates C<@foo> in scalar context. Previously
+it would be evaluated in list context, and since readline() pops only
+one argument from the stack, the stack could underflow, or be left
+with unexpected values on the stack. [L<perl #133989|https://rt.perl.org/Ticket/Display.html?id=133989>]
+
+=item *
+
+Parsing incomplete hex or binary literals was changed in 5.31.1 to treat such a
+literal as just the 0, leaving the following C<x> or C<b> to be parsed as part
+of the next token. This could lead to some silent changes in behaviour, so now
+incomplete hex or binary literals produce a fatal error.
+[L<perl #134125|https://rt.perl.org/Ticket/Display.html?id=134125>]
+
+=item *
+
+eval_pv()'s I<croak_on_error> flag will now throw even if the exception is a
+false overloaded value.
+[L<perl #134177|https://rt.perl.org/Ticket/Display.html?id=134177>]
+
+=item *
+
+C<INIT> blocks and the program itself are no longer run if exit(0) is called
+within a C<BEGIN>, C<UNITCHECK> or C<CHECK> block.
+[L<perl #2754|https://rt.perl.org/Ticket/Display.html?id=2754>]
+
+=item *
+
+C<< open my $fh, ">>+", undef >> now opens the temporary file in append mode:
+writes will seek to the end of file before writing.
+[L<perl #134221|https://rt.perl.org/Ticket/Display.html?id=134221>]
+
+=item *
+
+Fixed a SEGV when searching for the source of an uninitialized value warning on
+an op whose subtree includes an OP_MULTIDEREF.
+[L<perl #134275|https://rt.perl.org/Ticket/Display.html?id=134275>]
+
+=back
+
+=head1 Obituary
+
+Jeff Goff (JGOFF or DrForr), an integral part of the Perl and Raku
+communities and a dear friend to all of us, has passed away on March
+13th, 2020. DrForr was a prominent member of the communities, attending
+and speaking at countless events, contributing to numerous projects,
+and assisting and helping in any way he could.
+
+His passing leaves a hole in our hearts and in our communities and he
+will be sorely missed.
+
+=head1 Acknowledgements
+
+Perl 5.32.0 represents approximately 13 months of development since Perl
+5.30.0 and contains approximately 220,000 lines of changes across 1,800
+files from 89 authors.
+
+Excluding auto-generated files, documentation and release tools, there were
+approximately 140,000 lines of changes to 880 .pm, .t, .c and .h files.
+
+Perl continues to flourish into its fourth decade thanks to a vibrant
+community of users and developers. The following people are known to have
+contributed the improvements that became Perl 5.32.0:
+
+Aaron Crane, Alberto Simões, Alexandr Savca, Andreas König, Andrew Fresh,
+Andy Dougherty, Ask Bjørn Hansen, Atsushi Sugawara, Bernhard M. Wiedemann,
+brian d foy, Bryan Stenson, Chad Granum, Chase Whitener, Chris 'BinGOs'
+Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan Book, Daniel
+Dragan, Dan Kogai, Dave Cross, Dave Rolsky, David Cantrell, David Mitchell,
+Dominic Hargreaves, E. Choroba, Felipe Gasper, Florian Weimer, Graham Knop,
+Håkon Hægland, Hauke D, H.Merijn Brand, Hugo van der Sanden, Ichinose
+Shogo, James E Keenan, Jason McIntosh, Jerome Duval, Johan Vromans, John
+Lightsey, John Paul Adrian Glaubitz, Kang-min Liu, Karen Etheridge, Karl
+Williamson, Leon Timmermans, Manuel Mausz, Marc Green, Matthew Horsfall,
+Matt Turner, Max Maischein, Michael Haardt, Nicholas Clark, Nicolas R., Niko
+Tyni, Pali, Paul Evans, Paul Johnson, Paul Marquess, Peter Eisentraut, Peter
+John Acklam, Peter Oliver, Petr Písař, Renee Baecker, Ricardo Signes,
+Richard Leach, Russ Allbery, Samuel Smith, Santtu Ojanperä, Sawyer X,
+Sergey Aleynikov, Sergiy Borodych, Shirakata Kentaro, Shlomi Fish, Sisyphus,
+Slaven Rezic, Smylers, Stefan Seifert, Steve Hay, Steve Peters, Svyatoslav,
+Thibault Duponchelle, Todd Rinaldo, Tomasz Konojacki, Tom Hukins, Tony Cook,
+Unicode Consortium, VanL, Vickenty Fesunov, Vitali Peil, Yves Orton, Zefram.
+
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not include
+the names of the (very much appreciated) contributors who reported issues to
+the Perl bug tracker.
+
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors, please
+see the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the perl bug database
+at L<https://github.com/Perl/perl5/issues>. There may also be information at
+L<http://www.perl.org/>, the Perl Home Page.
+
+If you believe you have an unreported bug, please open an issue at
+L<https://github.com/Perl/perl5/issues>. Be sure to trim your bug down to a
+tiny but sufficient test case.
+
+If the bug you are reporting has security implications which make it
+inappropriate to send to a public issue tracker, 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
+
+The F<Changes> file for an explanation of how to view exhaustive details on
+what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index b92ea53c8a..64883315da 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1,999 +1,202 @@
-=pod
-
 =encoding utf8
 
 =head1 NAME
 
-perldelta - what is new for perl v5.32.0
+[ this is a template for a new perldelta file.  Any text flagged as XXX needs
+to be processed before release. ]
+
+perldelta - what is new for perl v5.32.1
 
 =head1 DESCRIPTION
 
-This document describes differences between the 5.30.0 release and the 5.32.0
+This document describes differences between the 5.32.0 release and the 5.32.1
 release.
 
-If you are upgrading from an earlier release such as 5.28.0, first read
-L<perl5300delta>, which describes differences between 5.28.0 and 5.30.0.
-
-=head1 Core Enhancements
-
-=head2 The isa Operator
-
-A new experimental infix operator called C<isa> tests whether a given object
-is an instance of a given class or a class derived from it:
-
-    if( $obj isa Package::Name ) { ... }
-
-For more detail see L<perlop/Class Instance Operator>.
-
-=head2 Unicode 13.0 is supported
-
-See L<https://www.unicode.org/versions/Unicode13.0.0/> for details.
-
-=head2 Chained comparisons capability
-
-Some comparison operators, as their associativity, I<chain> with some
-operators of the same precedence (but never with operators of different
-precedence).
-
-    if ( $x < $y <= $z ) {...}
-
-behaves exactly like:
-
-    if ( $x < $y && $y <= $z ) {...}
-
-(assuming that C<"$y"> is as simple a scalar as it looks.)
-
-You can read more about this in L<perlop> under
-L<perlop/Operator Precedence and Associativity>.
-
-=head2 New Unicode properties C<Identifier_Status> and C<Identifier_Type> supported
-
-Unicode is in the process of revising its regular expression
-requirements: L<https://www.unicode.org/draft/reports/tr18/tr18.html>.
-As part of that they are wanting more properties to be exposed, ones
-that aren't part of the strict UCD (Unicode character database). These
-two are used for examining inputs for security purposes. Details on
-their usage is at L<https://www.unicode.org/reports/tr39/proposed.html>.
-
-=head2 It is now possible to write C<qr/\p{Name=...}/>, or
-C<qr!\p{na=/(SMILING|GRINNING) FACE/}!>
-
-The Unicode Name property is now accessible in regular expression
-patterns, as an alternative to C<\N{...}>.
-A comparison of the two methods is given in
-L<perlunicode/Comparison of \N{...} and \p{name=...}>.
-
-The second example above shows that wildcard subpatterns are also usable
-in this property. See L<perlunicode/Wildcards in Property Values>.
-
-=head2 Improvement of C<POSIX::mblen()>, C<mbtowc>, and C<wctomb>
-
-The C<POSIX::mblen()>, C<mbtowc>, and C<wctomb> functions now
-work on shift state locales and are thread-safe on C99 and above
-compilers when executed on a platform that has locale thread-safety; the
-length parameters are now optional.
-
-These functions are always executed under the current C language locale.
-(See L<perllocale>.)  Most locales are stateless, but a few, notably the
-very rarely encountered ISO 2022, maintain a state between calls to
-these functions. Previously the state was cleared on every call, but
-now the state is not reset unless the appropriate parameter is C<undef>.
-
-On threaded perls, the C99 functions L<mbrlen(3)>, L<mbrtowc(3)>, and
-L<wcrtomb(3)>, when available, are substituted for the plain functions.
-This makes these functions thread-safe when executing on a locale
-thread-safe platform.
-
-The string length parameters in C<mblen> and C<mbtowc> are now optional;
-useful only if you wish to restrict the length parsed in the source
-string to less than the actual length.
+If you are upgrading from an earlier release such as 5.31.0, first read
+L<perl5320delta>, which describes differences between 5.31.0 and 5.32.0.
 
-=head2 Alpha assertions are no longer experimental
+=head1 Notice
 
-See L<perlre/(*pla:pattern)>, L<perlre/(*plb:pattern)>,
-L<perlre/(*nla:pattern)>>, and L<perlre/(*nlb:pattern)>.
-Use of these no longer generates a warning; existing code that disables
-the warning category C<experimental::alpha_assertions> will continue to work
-without any changes needed. Enabling the category has no effect.
+XXX Any important notices here
 
-=head2 Script runs are no longer experimental
-
-See L<perlre/Script Runs>. Use of these no longer generates a warning;
-existing code that disables the warning category
-C<experimental::script_run> will continue to work without any
-changes needed. Enabling the category has no effect.
-
-=head2 Feature checks are now faster
-
-Previously feature checks in the parser required a hash lookup when
-features were set outside of a feature bundle, this has been optimized
-to a bit mask check. [L<GH #17229|https://github.com/Perl/perl5/issues/17229>]
-
-=head2 Perl is now developed on GitHub
-
-Perl is now developed on GitHub. You can find us at
-L<https://github.com/Perl/perl5>.
-
-Non-security bugs should now be reported via GitHub. Security issues should
-continue to be reported as documented in L<perlsec>.
+=head1 Core Enhancements
 
-=head2 Compiled patterns can now be dumped before optimization
+XXX New core language features go here.  Summarize user-visible core language
+enhancements.  Particularly prominent performance optimisations could go
+here, but most should go in the L</Performance Enhancements> section.
 
-This is primarily useful for tracking down bugs in the regular
-expression compiler. This dump happens on C<-DDEBUGGING> perls, if you
-specify C<-Drv> on the command line; or on any perl if the pattern is
-compiled within the scope of S<C<use re qw(Debug DUMP_PRE_OPTIMIZE)>> or
-S<C<use re qw(Debug COMPILE EXTRA)>>. (All but the second case display
-other information as well.)
+[ List each enhancement as a =head2 entry ]
 
 =head1 Security
 
-=head2 [CVE-2020-10543] Buffer overflow caused by a crafted regular expression
-
-A signed C<size_t> integer overflow in the storage space calculations for
-nested regular expression quantifiers could cause a heap buffer overflow in
-Perl's regular expression compiler that overwrites memory allocated after the
-regular expression storage space with attacker supplied data.
-
-The target system needs a sufficient amount of memory to allocate partial
-expansions of the nested quantifiers prior to the overflow occurring.  This
-requirement is unlikely to be met on 64-bit systems.
-
-Discovered by: ManhND of The Tarantula Team, VinCSS (a member of Vingroup).
-
-=head2 [CVE-2020-10878] Integer overflow via malformed bytecode produced by a crafted regular expression
-
-Integer overflows in the calculation of offsets between instructions for the
-regular expression engine could cause corruption of the intermediate language
-state of a compiled regular expression.  An attacker could abuse this behaviour
-to insert instructions into the compiled form of a Perl regular expression.
-
-Discovered by: Hugo van der Sanden and Slaven Rezic.
-
-=head2 [CVE-2020-12723] Buffer overflow caused by a crafted regular expression
+XXX Any security-related notices go here.  In particular, any security
+vulnerabilities closed should be noted here rather than in the
+L</Selected Bug Fixes> section.
 
-Recursive calls to C<S_study_chunk()> by Perl's regular expression compiler to
-optimize the intermediate language representation of a regular expression could
-cause corruption of the intermediate language state of a compiled regular
-expression.
-
-Discovered by: Sergey Aleynikov.
-
-=head2 Additional Note
-
-An application written in Perl would only be vulnerable to any of the above
-flaws if it evaluates regular expressions supplied by the attacker.  Evaluating
-regular expressions in this fashion is known to be dangerous since the regular
-expression engine does not protect against denial of service attacks in this
-usage scenario.
+[ List each security issue as a =head2 entry ]
 
 =head1 Incompatible Changes
 
-=head2 Certain pattern matching features are now prohibited in compiling
-Unicode property value wildcard subpatterns
-
-These few features are either inappropriate or interfere with the
-algorithm used to accomplish this task. The complete list is in
-L<perlunicode/Wildcards in Property Values>.
-
-=head2 Unused functions C<POSIX::mbstowcs> and C<POSIX::wcstombs> are removed
-
-These functions could never have worked due to a defective interface
-specification. There is clearly no demand for them, given that no one
-has ever complained in the many years the functions were claimed to be
-available, hence so-called "support" for them is now dropped.
-
-=head2 A bug fix for C<(?[...])> may have caused some patterns to no
-longer compile
-
-See L</Selected Bug Fixes>. The heuristics previously used may have let
-some constructs compile (perhaps not with the programmer's intended
-effect) that should have been errors. None are known, but it is
-possible that some erroneous constructs no longer compile.
-
-=head2 C<\p{I<user-defined>}> properties now always override official
-Unicode ones
-
-Previously, if and only if a user-defined property was declared prior to
-the compilation of the regular expression pattern that contains it, its
-definition was used instead of any official Unicode property with the
-same name. Now, it always overrides the official property. This
-change could break existing code that relied (likely unwittingly) on the
-previous behavior. Without this fix, if Unicode released a new version
-with a new property that happens to have the same name as the one you
-had long been using, your program would break when you upgraded to a
-perl that used that new Unicode version. See L<perlunicode/User-Defined
-Character Properties>. [L<GH #17205|https://github.com/Perl/perl5/issues/17205>]
-
-=head2 Modifiable variables are no longer permitted in constants
-
-Code like:
-
-    my $var;
-    $sub = sub () { $var };
+XXX For a release on a stable branch, this section aspires to be:
 
-where C<$var> is referenced elsewhere in some sort of modifiable context now
-produces an exception when the sub is defined.
+    There are no changes intentionally incompatible with 5.XXX.XXX
+    If any exist, they are bugs, and we request that you submit a
+    report.  See L</Reporting Bugs> below.
 
-This error can be avoided by adding a return to the sub definition:
+[ List each incompatible change as a =head2 entry ]
 
-    $sub = sub () { return $var };
+=head1 Deprecations
 
-This has been deprecated since Perl 5.22.
-[L<perl #134138|https://rt.perl.org/Ticket/Display.html?id=134138>]
+XXX Any deprecated features, syntax, modules etc. should be listed here.
 
-=head2 Use of L<C<vec>|perlfunc/vec EXPR,OFFSET,BITS> on strings with code points above 0xFF is forbidden
+=head2 Module removals
 
-Such strings are represented internally in UTF-8, and C<vec> is a
-bit-oriented operation that will likely give unexpected results on those
-strings. This was deprecated in perl 5.28.0.
-
-=head2 Use of code points over 0xFF in string bitwise operators
-
-Some uses of these were already illegal after a previous deprecation
-cycle. The remaining uses are now prohibited, having been deprecated in perl
-5.28.0. See L<perldeprecation>.
-
-=head2 C<Sys::Hostname::hostname()> does not accept arguments
-
-This usage was deprecated in perl 5.28.0 and is now fatal.
-
-=head2 Plain "0" string now treated as a number for range operator
-
-Previously a range C<"0" .. "-1"> would produce a range of numeric
-strings from "0" through "99"; this now produces an empty list, just
-as C<0 .. -1> does. This also means that C<"0" .. "9"> now produces a
-list of integers, where previously it would produce a list of strings.
-
-This was due to a special case that treated strings starting with "0"
-as strings so ranges like C<"00" .. "03"> produced C<"00", "01", "02", "03">,
-but didn't specially handle the string C<"0">.
-[L<perl #133695|https://rt.perl.org/Ticket/Display.html?id=133695>]
-
-=head2 C<\K> now disallowed in look-ahead and look-behind assertions
-
-This was disallowed because it causes unexpected behaviour, and no-one
-could define what the desired behaviour should be.
-[L<perl #124256|https://rt.perl.org/Ticket/Display.html?id=124256>]
-
-=head1 Performance Enhancements
-
-=over 4
-
-=item *
-
-C<my_strnlen> has been sped up for systems that don't have their own
-C<strnlen> implementation.
-
-=item *
-
-C<grok_bin_oct_hex> (and so, C<grok_bin>, C<grok_oct>, and C<grok_hex>)
-have been sped up.
-
-=item *
-
-C<grok_number_flags> has been sped up.
-
-=item *
-
-C<sort> is now noticeably faster in cases such as C<< sort {$a <=> $b} >> or
-C<< sort {$b <=> $a} >>. [L<GH #17608|https://github.com/Perl/perl5/pull/17608>]
-
-=back
-
-=head1 Modules and Pragmata
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<Archive::Tar> has been upgraded from version 2.32 to 2.36.
-
-=item *
-
-L<autodie> has been upgraded from version 2.29 to 2.32.
-
-=item *
-
-L<B> has been upgraded from version 1.76 to 1.80.
-
-=item *
-
-L<B::Deparse> has been upgraded from version 1.49 to 1.54.
-
-=item *
-
-L<Benchmark> has been upgraded from version 1.22 to 1.23.
-
-=item *
-
-L<charnames> has been upgraded from version 1.45 to 1.48.
-
-=item *
+XXX Remove this section if not applicable.
 
-L<Class::Struct> has been upgraded from version 0.65 to 0.66.
-
-=item *
-
-L<Compress::Raw::Bzip2> has been upgraded from version 2.084 to 2.093.
-
-=item *
-
-L<Compress::Raw::Zlib> has been upgraded from version 2.084 to 2.093.
-
-=item *
-
-L<CPAN> has been upgraded from version 2.22 to 2.27.
-
-=item *
-
-L<DB_File> has been upgraded from version 1.843 to 1.853.
-
-=item *
-
-L<Devel::PPPort> has been upgraded from version 3.52 to 3.57.
-
-The test files generated on Win32 are now identical to when they are
-generated on POSIX-like systems.
-
-=item *
-
-L<diagnostics> has been upgraded from version 1.36 to 1.37.
-
-=item *
-
-L<Digest::MD5> has been upgraded from version 2.55 to 2.55_01.
-
-=item *
-
-L<Dumpvalue> has been upgraded from version 1.18 to 1.21.
-
-Previously, when dumping elements of an array and encountering an undefined
-value, the string printed would have been C<empty array>. This has been
-changed to what was apparently originally intended:  C<empty slot>.
-
-=item *
-
-L<DynaLoader> has been upgraded from version 1.45 to 1.47.
-
-=item *
-
-L<Encode> has been upgraded from version 3.01 to 3.06.
-
-=item *
-
-L<encoding> has been upgraded from version 2.22 to 3.00.
-
-=item *
-
-L<English> has been upgraded from version 1.10 to 1.11.
-
-=item *
-
-L<Exporter> has been upgraded from version 5.73 to 5.74.
-
-=item *
-
-L<ExtUtils::CBuilder> has been upgraded from version 0.280231 to 0.280234.
-
-=item *
-
-L<ExtUtils::MakeMaker> has been upgraded from version 7.34 to 7.44.
-
-=item *
-
-L<feature> has been upgraded from version 1.54 to 1.58.
-
-A new C<indirect> feature has been added, which is enabled by default
-but allows turning off L<indirect object syntax|perlobj/Indirect
-Object Syntax>.
-
-=item *
-
-L<File::Find> has been upgraded from version 1.36 to 1.37.
-
-On Win32, the tests no longer require either a file in the drive root
-directory, or a writable root directory.
-
-=item *
-
-L<File::Glob> has been upgraded from version 1.32 to 1.33.
-
-=item *
-
-L<File::stat> has been upgraded from version 1.08 to 1.09.
-
-=item *
-
-L<Filter::Simple> has been upgraded from version 0.95 to 0.96.
-
-=item *
-
-L<Getopt::Long> has been upgraded from version 2.5 to 2.51.
-
-=item *
-
-L<Hash::Util> has been upgraded from version 0.22 to 0.23.
-
-The Synopsis has been updated as the example code stopped working with
-newer perls.
-[L<GH #17399|https://github.com/Perl/perl5/issues/17399>]
-
-=item *
-
-L<I18N::Langinfo> has been upgraded from version 0.18 to 0.19.
-
-=item *
-
-L<I18N::LangTags> has been upgraded from version 0.43 to 0.44.
-
-Document the C<IGNORE_WIN32_LOCALE> environment variable.
-
-=item *
-
-L<IO> has been upgraded from version 1.40 to 1.43.
-
-L<IO::Socket> no longer caches a zero protocol value, since this
-indicates that the implementation will select a protocol. This means
-that on platforms that don't implement C<SO_PROTOCOL> for a given
-socket type the protocol method may return C<undef>.
-
-The supplied I<TO> is now always honoured on calls to the C<send()>
-method. [L<perl #133936|https://rt.perl.org/Ticket/Display.html?id=133936>]
-
-=item *
-
-IO-Compress has been upgraded from version 2.084 to 2.093.
-
-=item *
-
-L<IPC::Cmd> has been upgraded from version 1.02 to 1.04.
-
-=item *
-
-L<IPC::Open3> has been upgraded from version 1.20 to 1.21.
-
-=item *
-
-L<JSON::PP> has been upgraded from version 4.02 to 4.04.
-
-=item *
-
-L<Math::BigInt> has been upgraded from version 1.999816 to 1.999818.
-
-=item *
-
-L<Math::BigInt::FastCalc> has been upgraded from version 0.5008 to 0.5009.
-
-=item *
-
-L<Module::CoreList> has been upgraded from version 5.20190522 to 5.20200620.
-
-=item *
+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.
 
-L<Module::Load::Conditional> has been upgraded from version 0.68 to 0.70.
+The core versions of these modules will now issue C<"deprecated">-category
+warnings to alert you to this fact.  To silence these deprecation warnings,
+install the modules in question from CPAN.
 
-=item *
-
-L<Module::Metadata> has been upgraded from version 1.000036 to 1.000037.
-
-=item *
-
-L<mro> has been upgraded from version 1.22 to 1.23.
-
-=item *
-
-L<Net::Ping> has been upgraded from version 2.71 to 2.72.
-
-=item *
-
-L<Opcode> has been upgraded from version 1.43 to 1.47.
-
-=item *
-
-L<open> has been upgraded from version 1.11 to 1.12.
-
-=item *
-
-L<overload> has been upgraded from version 1.30 to 1.31.
-
-=item *
-
-L<parent> has been upgraded from version 0.237 to 0.238.
-
-=item *
-
-L<perlfaq> has been upgraded from version 5.20190126 to 5.20200523.
-
-=item *
-
-L<PerlIO> has been upgraded from version 1.10 to 1.11.
-
-=item *
-
-L<PerlIO::encoding> has been upgraded from version 0.27 to 0.28.
-
-=item *
-
-L<PerlIO::via> has been upgraded from version 0.17 to 0.18.
-
-=item *
-
-L<Pod::Html> has been upgraded from version 1.24 to 1.25.
-
-=item *
-
-L<Pod::Simple> has been upgraded from version 3.35 to 3.40.
-
-=item *
-
-L<podlators> has been upgraded from version 4.11 to 4.14.
-
-=item *
-
-L<POSIX> has been upgraded from version 1.88 to 1.94.
-
-=item *
-
-L<re> has been upgraded from version 0.37 to 0.40.
-
-=item *
-
-L<Safe> has been upgraded from version 2.40 to 2.41.
-
-=item *
-
-L<Scalar::Util> has been upgraded from version 1.50 to 1.55.
-
-=item *
-
-L<SelfLoader> has been upgraded from version 1.25 to 1.26.
-
-=item *
-
-L<Socket> has been upgraded from version 2.027 to 2.029.
-
-=item *
-
-L<Storable> has been upgraded from version 3.15 to 3.21.
-
-Use of C<note()> from L<Test::More> is now optional in tests. This works
-around a circular dependency with L<Test::More> when installing on very
-old perls from CPAN.
-
-Vstring magic strings over 2GB are now disallowed.
-
-Regular expressions objects weren't properly counted for object id
-purposes on retrieve. This would corrupt the resulting structure, or
-cause a runtime error in some cases. [L<perl #134179|https://rt.perl.org/Ticket/Display.html?id=134179>]
-
-=item *
-
-L<Sys::Hostname> has been upgraded from version 1.22 to 1.23.
-
-=item *
-
-L<Sys::Syslog> has been upgraded from version 0.35 to 0.36.
-
-=item *
-
-L<Term::ANSIColor> has been upgraded from version 4.06 to 5.01.
-
-=item *
-
-L<Test::Simple> has been upgraded from version 1.302162 to 1.302175.
-
-=item *
-
-L<Thread> has been upgraded from version 3.04 to 3.05.
-
-=item *
-
-L<Thread::Queue> has been upgraded from version 3.13 to 3.14.
-
-=item *
-
-L<threads> has been upgraded from version 2.22 to 2.25.
-
-=item *
-
-L<threads::shared> has been upgraded from version 1.60 to 1.61.
-
-=item *
-
-L<Tie::File> has been upgraded from version 1.02 to 1.06.
-
-=item *
-
-L<Tie::Hash::NamedCapture> has been upgraded from version 0.10 to 0.13.
-
-=item *
-
-L<Tie::Scalar> has been upgraded from version 1.04 to 1.05.
-
-=item *
-
-L<Tie::StdHandle> has been upgraded from version 4.5 to 4.6.
-
-=item *
-
-L<Time::HiRes> has been upgraded from version 1.9760 to 1.9764.
-
-Removed obsolete code such as support for pre-5.6 perl and classic
-MacOS. [L<perl #134288|https://rt.perl.org/Ticket/Display.html?id=134288>]
-
-=item *
-
-L<Time::Piece> has been upgraded from version 1.33 to 1.3401.
-
-=item *
-
-L<Unicode::Normalize> has been upgraded from version 1.26 to 1.27.
-
-=item *
-
-L<Unicode::UCD> has been upgraded from version 0.72 to 0.75.
-
-=item *
-
-L<VMS::Stdio> has been upgraded from version 2.44 to 2.45.
-
-=item *
-
-L<warnings> has been upgraded from version 1.44 to 1.47.
-
-=item *
-
-L<Win32> has been upgraded from version 0.52 to 0.53.
-
-=item *
-
-L<Win32API::File> has been upgraded from version 0.1203 to 0.1203_01.
-
-=item *
-
-L<XS::APItest> has been upgraded from version 1.00 to 1.09.
-
-=back
-
-=head2 Removed Modules and Pragmata
-
-=over 4
-
-=item *
-
-Pod::Parser has been removed from the core distribution.
-It still is available for download from CPAN. This resolves [L<perl
-#119439|https://rt.perl.org/Ticket/Display.html?id=119439>].
-
-=back
-
-=head1 Documentation
-
-=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, open an issue
-at L<https://github.com/Perl/perl5/issues>.
-
-Additionally, the following selected changes have been made:
-
-=head3 L<perldebguts>
-
-=over 4
-
-=item *
-
-Simplify a few regnode definitions
-
-Update C<BOUND> and C<NBOUND> definitions.
-
-=item *
-
-Add ANYOFHs regnode
-
-This node is like C<ANYOFHb>, but is used when more than one leading byte
-is the same in all the matched code points.
-
-C<ANYOFHb> is used to avoid having to convert from UTF-8 to code point for
-something that won't match. It checks that the first byte in the UTF-8
-encoded target is the desired one, thus ruling out most of the possible
-code points.
-
-=back
-
-=head3 L<perlapi>
-
-=over 4
-
-=item *
-
-C<sv_2pvbyte> updated to mention it will croak if the SV cannot be
-downgraded.
-
-=item *
-
-C<sv_setpvn> updated to mention that the UTF-8 flag will not be changed by
-this function, and a terminating NUL byte is guaranteed.
-
-=item *
-
-Documentation for C<PL_phase> has been added.
-
-=item *
-
-The documentation for C<grok_bin>, C<grok_oct>, and C<grok_hex> has been
-updated and clarified.
-
-=back
-
-=head3 L<perldiag>
-
-=over 4
-
-=item *
-
-Add documentation for experimental 'isa' operator
-
-(S experimental::isa) This warning is emitted if you use the (C<isa>)
-operator. This operator is currently experimental and its behaviour may
-change in future releases of Perl.
-
-=back
-
-=head3 L<perlfunc>
-
-=over 4
-
-=item C<caller>
-
-Like L<C<__FILE__>|/__FILE__> and L<C<__LINE__>|/__LINE__>, the filename and
-line number returned here may be altered by the mechanism described at
-L<perlsyn/"Plain Old Comments (Not!)">.
-
-=item C<__FILE__>
-
-It can be altered by the mechanism described at
-L<perlsyn/"Plain Old Comments (Not!)">.
-
-=item C<__LINE__>
-
-It can be altered by the mechanism described at
-L<perlsyn/"Plain Old Comments (Not!)">.
-
-=item C<return>
-
-Now mentions that you cannot return from C<do BLOCK>.
-
-=item C<open>
-
-The C<open()> section had been renovated significantly.
-
-=back
-
-=head3 L<perlguts>
-
-=over 4
-
-=item *
-
-No longer suggesting using perl's C<malloc>. Modern system C<malloc> is
-assumed to be much better than perl's implementation now.
-
-=item *
+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
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
 
-Documentation about F<embed.fnc> flags has been removed. F<embed.fnc> now has
-sufficient comments within it. Anyone changing that file will see those
-comments first, so entries here are now redundant.
-
-=item *
-
-Updated documentation for C<UTF8f>
-
-=item *
-
-Added missing C<=for apidoc> lines
-
-=back
-
-=head3 L<perlhacktips>
-
-=over 4
-
-=item *
-
-The differences between Perl strings and C strings are now detailed.
-
-=back
-
-=head3 L<perlintro>
-
-=over 4
+=over
 
-=item *
+=item XXX
 
-The documentation for the repetition operator C<x> have been clarified.
-[L<GH #17335|https://github.com/Perl/perl5/issues/17335>]
+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.
 
 =back
 
-=head3 L<perlipc>
+[ List each other deprecation as a =head2 entry ]
 
-=over 4
-
-=item *
-
-The documentation surrounding C<open> and handle usage has been modernized
-to prefer 3-arg open and lexical variables instead of barewords.
-
-=item *
-
-Various updates and fixes including making all examples strict-safe and
-replacing C<-w> with C<use warnings>.
+=head1 Performance Enhancements
 
-=back
+XXX Changes which enhance performance without changing behaviour go here.
+There may well be none in a stable release.
 
-=head3 L<perlop>
+[ List each enhancement as an =item entry ]
 
 =over 4
 
 =item *
 
-'isa' operator is experimental
-
-This is an experimental feature and is available when enabled
-by C<use feature 'isa'>. It emits a warning in the C<experimental::isa>
-category.
+XXX
 
 =back
 
-=head3 L<perlpod>
-
-=over 4
-
-=item *
-
-Details of the various stacks within the perl interpreter are now explained
-here.
+=head1 Modules and Pragmata
 
-=item *
+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>.  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.
 
-Advice has been added regarding the usage of C<< ZE<lt>E<gt> >>.
+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.)
 
-=back
+[ Within each section, list entries as an =item entry ]
 
-=head3 L<perlport>
+=head2 New Modules and Pragmata
 
 =over 4
 
 =item *
 
-Update C<timegm> example to use the correct year format I<1970> instead of I<70>.
-[L<GH #16431|https://github.com/Perl/perl5/issues/16431>]
+XXX Remove this section if not applicable.
 
 =back
 
-=head3 L<perlreref>
+=head2 Updated Modules and Pragmata
 
 =over 4
 
 =item *
 
-Fix some typos.
+L<XXX> has been upgraded from version A.xx to B.yy.
 
-=back
-
-=head3 L<perlvar>
-
-=over 4
-
-=item *
-
-Now recommends stringifying C<$]> and comparing it numerically.
+If there was something important to note about this change, include that here.
 
 =back
 
-=head3 L<perlapi>, L<perlintern>
+=head2 Removed Modules and Pragmata
 
 =over 4
 
 =item *
 
-Documentation has been added for several functions that were
-lacking it before.
+XXX
 
 =back
 
-=head3 L<perlxs>
-
-=over 4
-
-=item *
-
-Suggest using C<libffi> for simple library bindings.
+=head1 Documentation
 
-=back
+XXX Changes to files in F<pod/> go here.  Consider grouping entries by
+file and be sure to link to the appropriate page, e.g. L<perlfunc>.
 
-=head3 L<POSIX>
+=head2 New Documentation
 
-=over 4
+XXX Changes which create B<new> files in F<pod/> go here.
 
-=item *
+=head3 L<XXX>
 
-C<setlocale> warning about threaded builds updated to note it does not
-apply on Perl 5.28.X and later.
+XXX Description of the purpose of the new file here
 
-=item *
+=head2 Changes to Existing Documentation
 
-C<< Posix::SigSet->new(...) >> updated to state it throws an error if any of
-the supplied signals cannot be added to the set.
+We have attempted to update the documentation to reflect the changes
+listed in this document.  If you find any we have missed, open an issue
+at L<https://github.com/Perl/perl5/issues>.
 
-=back
+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 Updating of links
+=head3 L<XXX>
 
 =over 4
 
 =item *
 
-Links to the now defunct L<https://search.cpan.org> site now point at
-the equivalent L<https://metacpan.org> URL. [L<GH #17393|https://github.com/Perl/perl5/issues/17393>]
-
-=item *
-
-The man page for L<ExtUtils::XSSymSet> is now only installed on VMS,
-which is the only platform the module is installed on. [L<GH #17424|https://github.com/Perl/perl5/issues/17424>]
-
-=item *
-
-URLs have been changed to C<https://> and stale links have been updated.
-
-Where applicable, the URLs in the documentation have been moved from using the
-C<http://> protocol to C<https://>. This also affects the location of the bug
-tracker at L<https://rt.perl.org>.
-
-=item *
-
-Some links to OS/2 libraries, Address Sanitizer and other system tools had gone
-stale. These have been updated with working links.
-
-=item *
-
-Some links to old email addresses on perl5-porters had gone stale. These have been
-updated with working links.
+XXX Description of the change here
 
 =back
 
 =head1 Diagnostics
 
 The following additions or changes have been made to diagnostic output,
-including warnings and fatal error messages. For the complete list of
+including warnings and fatal error messages.  For the complete list of
 diagnostic messages, see L<perldiag>.
 
+XXX New or changed warnings emitted by the core's C<C> code go here.  Also
+include any changes in L<perldiag> that reconcile it to the C<C> code.
+
 =head2 New Diagnostics
 
+XXX Newly added diagnostic messages go under here, separated into New Errors
+and New Warnings
+
 =head3 New Errors
 
 =over 4
 
 =item *
 
-L<Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>
-|perldiag/"Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>">
-
-This is a replacement for several error messages listed under
-L</Changes to Existing Diagnostics>.
-
-=item *
-
-C<L<No digits found for %s literal|perldiag/"No digits found for %s literal">>
-
-(F) No hexadecimal digits were found following C<0x> or no binary digits were
-found following C<0b>.
+XXX L<message|perldiag/"message">
 
 =back
 
@@ -1003,891 +206,213 @@ found following C<0b>.
 
 =item *
 
-L<Code point 0x%X is not Unicode, and not portable|perldiag/"Code point 0x%X is not Unicode, and not portable">
-
-This is actually not a new message, but it is now output when the
-warnings category C<portable> is enabled.
-
-When raised during regular expression pattern compilation, the warning
-has extra text added at the end marking where precisely in the pattern
-it occurred.
-
-=item *
-
-L<Non-hex character '%c' terminates \x early.  Resolved as "%s"|perldiag/"Non-hex character '%c' terminates \x early.  Resolved as "%s"">
-
-This replaces a warning that was much less specific, and which gave
-false information. This new warning parallels the similar
-already-existing one raised for C<\o{}>.
+XXX L<message|perldiag/"message">
 
 =back
 
 =head2 Changes to Existing Diagnostics
 
-=over 4
-
-=item *
-
-L<Character following "\c" must be printable ASCII|perldiag/"Character following "\c" must be printable ASCII">
-
-...now has extra text added at the end, when raised during regular
-expression pattern compilation, marking where precisely in the pattern
-it occurred.
-
-=item *
-
-L<Use "%s" instead of "%s"|perldiag/"Use "%s" instead of "%s"">
-
-...now has extra text added at the end, when raised during regular
-expression pattern compilation, marking where precisely in the pattern
-it occurred.
-
-=item *
-
-L<Sequence "\c{" invalid|perldiag/"Sequence "\c{" invalid">
-
-...now has extra text added at the end, when raised during regular
-expression pattern compilation, marking where precisely in the pattern
-it occurred.
-
-=item *
-
-L<"\c%c" is more clearly written simply as "%s"|perldiag/""\c%c" is more clearly written simply as "%s"">
-
-...now has extra text added at the end, when raised during regular
-expression pattern compilation, marking where precisely in the pattern
-it occurred.
-
-=item *
-
-L<Non-octal character '%c' terminates \o early.  Resolved as "%s"|perldiag/"Non-octal character '%c' terminates \o early.  Resolved as "%s"">
-
-...now includes the phrase "terminates \o early", and has extra text added
-at the end, when raised during regular expression pattern compilation,
-marking where precisely in the pattern it occurred. In some instances
-the text of the resolution has been clarified.
-
-=item *
-
-L<'%s' resolved to '\o{%s}%d'|perldiag/'%s' resolved to '\o{%s}%d'>
-
-As of Perl 5.32, this message is no longer generated. Instead,
-L<perldiag/Non-octal character '%c' terminates \o early.  Resolved as "%s">
-is used instead.
-
-=item *
-
-L<Use of code point 0x%s is not allowed; the permissible max is 0x%X|perldiag/"Use of code point 0x%s is not allowed; the permissible max is 0x%X">
-
-Some instances of this message previously output the hex digits C<A>,
-C<B>, C<C>, C<D>, C<E>, and C<F> in lower case. Now they are all
-consistently upper case.
-
-=item *
-
-The following three diagnostics have been removed, and replaced by
-L<C<Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>>
-|perldiag/"Expecting interpolated extended charclass in regex; marked by <-- HERE in mE<sol>%sE<sol>">:
-C<Expecting close paren for nested extended charclass in regex; marked
-by <-- HERE in mE<sol>%sE<sol>>,
-C<Expecting close paren for wrapper for nested extended charclass in
-regex; marked by <-- HERE in mE<sol>%sE<sol>>,
-and
-C<Expecting '(?flags:(?[...' in regex; marked by S<<-- HERE> in mE<sol>%sE<sol>>.
+XXX Changes (i.e. rewording) of diagnostic messages go here
 
-=item *
-
-The C<Code point 0x%X is not Unicode, and not portable> warning removed
-the line C<Code points above 0xFFFF_FFFF require larger than a 32 bit word.>
-as code points that large are no longer legal on 32-bit platforms.
-
-=item *
-
-L<Can't use global %s in %s|perldiag/"Can't use global %s in %s">
-
-This error message has been slightly reformatted from the original C<Can't use
-global %s in "%s">, and in particular misleading error messages like C<Can't
-use global $_ in "my"> are now rendered as C<Can't use global $_ in subroutine
-signature>.
-
-=item *
-
-L<Constants from lexical variables potentially modified elsewhere are no longer permitted|perldiag/"Constants from lexical variables potentially modified elsewhere are no longer permitted">
-
-This error message replaces the former C<Constants from lexical variables
-potentially modified elsewhere are deprecated. This will not be allowed in Perl
-5.32> to reflect the fact that this previously deprecated usage has now been
-transformed into an exception. The message's classification has also been
-updated from D (deprecated) to F (fatal).
-
-See also L</Incompatible Changes>.
+=over 4
 
 =item *
 
-C<\N{} here is restricted to one character> is now emitted in the same
-circumstances where previously C<\N{} in inverted character class or as a range
-end-point is restricted to one character> was.
-
-This is due to new circumstances having been added in Perl 5.30 that weren't
-covered by the earlier wording.
+XXX Describe change here
 
 =back
 
 =head1 Utility Changes
 
-=head2 L<perlbug>
+XXX Changes to installed programs such as F<perldoc> and F<xsubpp> go here.
+Most of these are built within the directory F<utils>.
 
-=over 4
-
-=item * The bug tracker homepage URL now points to GitHub.
-
-=back
+[ 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. ]
 
-=head2 L<streamzip>
+=head2 L<XXX>
 
 =over 4
 
 =item *
 
-This is a new utility, included as part of an
-L<IO::Compress::Base> upgrade.
-
-L<streamzip> creates a zip file from stdin. The program will read data
-from stdin, compress it into a zip container and, by default, write a
-streamed zip file to stdout.
+XXX
 
 =back
 
 =head1 Configuration and Compilation
 
-=head2 F<Configure>
-
-=over 4
-
-=item *
-
-For clang++, add C<< #include <stdlib.h> >> to Configure's probes for
-C<futimes>, C<strtoll>, C<strtoul>, C<strtoull>, C<strtouq>, otherwise the
-probes would fail to compile.
-
-=item *
-
-Use a compile and run test for C<lchown> to satisfy clang++ which should
-more reliably detect it.
-
-=item *
-
-For C++ compilers, add C<< #include <stdio.h> >> to Configure's probes for
-C<getpgrp> and C<setpgrp> as they use printf and C++ compilers may fail
-compilation instead of just warning.
-
-=item *
-
-Check if the compiler can handle inline attribute.
-
-=item *
-
-Check for character data alignment.
-
-=item *
-
-F<Configure> now correctly handles gcc-10. Previously it was interpreting it
-as gcc-1 and turned on C<-fpcc-struct-return>.
-
-=item *
-
-Perl now no longer probes for C<d_u32align>, defaulting to C<define> on all
-platforms. This check was error-prone when it was done, which was on 32-bit
-platforms only.
-[L<perl #133495|https://rt.perl.org/Ticket/Display.html?id=133495>]
-
-=item *
-
-Documentation and hints for building perl on Z/OS (native EBCDIC) have been
-updated. This is still a work in progress.
-
-=item *
-
-A new probe for C<malloc_usable_size> has been added.
-
-=item *
-
-Improvements in F<Configure> to detection in C++ and clang++. Work ongoing by
-Andy Dougherty. [L<perl #134171|https://rt.perl.org/Ticket/Display.html?id=134171>]
-
-=item *
-
-F<autodoc.pl>
+XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
+go here.  Any other changes to the Perl build process should be listed here.
+However, any platform-specific changes should be listed in the
+L</Platform Support> section, instead.
 
-This tool that regenerates L<perlintern> and L<perlapi> has been overhauled
-significantly, restoring consistency in flags used in F<embed.fnc> and
-L<Devel::PPPort> and allowing removal of many redundant C<=for apidoc>
-entries in code.
+[ List changes as an =item entry ].
 
-=item *
-
-The C<ECHO> macro is now defined. This is used in a C<dtrace> rule that was
-originally changed for FreeBSD, and the FreeBSD make apparently predefines it.
-The Solaris make does not predefine C<ECHO> which broke this rule on Solaris.
-[L<perl #134218|https://rt.perl.org/Ticket/Display.html?id=134218>]
+=over 4
 
 =item *
 
-Bison versions 3.1 through 3.4 are now supported.
+XXX
 
 =back
 
 =head1 Testing
 
-Tests were added and changed to reflect the other additions and
-changes in this release. Furthermore, these significant changes were
-made:
+XXX Any significant changes to the testing of a freshly built perl should be
+listed here.  Changes which create B<new> files in F<t/> go here as do any
+large changes to the testing harness (e.g. when parallel testing was added).
+Changes to existing files in F<t/> aren't worth summarizing, although the bugs
+that they represent may be covered elsewhere.
 
-=over 4
+XXX If there were no significant test changes, say this:
 
-=item *
-
-F<t/run/switches.t> no longer uses (and re-uses) the F<tmpinplace/>
-directory under F<t/>. This may prevent spurious failures. [L<GH #17424|https://github.com/Perl/perl5/issues/17424>]
-
-=item *
-
-Various bugs in C<POSIX::mbtowc> were fixed. Potential races with
-other threads are now avoided, and previously the returned wide
-character could well be garbage.
-
-=item *
+Tests were added and changed to reflect the other additions and changes
+in this release.
 
-Various bugs in C<POSIX::wctomb> were fixed. Potential races with other
-threads are now avoided, and previously it would segfault if the string
-parameter was shared or hadn't been pre-allocated with a string of
-sufficient length to hold the result.
+XXX If instead there were significant changes, say this:
 
-=item *
-
-Certain test output of scalars containing control characters and Unicode
-has been fixed on EBCDIC.
-
-=item *
+Tests were added and changed to reflect the other additions and
+changes in this release.  Furthermore, these significant changes were
+made:
 
-F<t/charset_tools.pl>: Avoid some work on ASCII platforms.
+[ List each test improvement as an =item entry ]
 
-=item *
-
-F<t/re/regexp.t>: Speed up many regex tests on ASCII platform
+=over 4
 
 =item *
 
-F<t/re/pat.t>: Skip tests that don't work on EBCDIC.
+XXX
 
 =back
 
 =head1 Platform Support
 
-=head2 Discontinued Platforms
-
-=over 4
-
-=item Windows CE
+XXX Any changes to platform support should be listed in the sections below.
 
-Support for building perl on Windows CE has now been removed.
+[ Within the sections, list each platform as an =item entry with specific
+changes as paragraphs below it. ]
 
-=back
+=head2 New Platforms
 
-=head2 Platform-Specific Notes
+XXX List any platforms that this version of perl compiles on, that previous
+versions did not.  These will either be enabled by new files in the F<hints/>
+directories, or new subdirectories and F<README> files at the top level of the
+source tree.
 
 =over 4
 
-=item Linux
-
-C<cc> will be used to populate C<plibpth> if C<cc> is C<clang>.
-[L<perl #134189|https://rt.perl.org/Ticket/Display.html?id=134189>]
-
-=item NetBSD 8.0
-
-Fix compilation of Perl on NetBSD 8.0 with g++.
-[L<GH #17381|https://github.com/Perl/perl5/issues/17381>]
-
-=item Windows
-
-=over 4
-
-=item *
-
-The configuration for C<ccflags> and C<optimize> are now separate, as
-with POSIX platforms. [L<GH #17156|https://github.com/Perl/perl5/issues/17156>]
-
-=item *
-
-Support for building perl with Visual C++ 6.0 has now been removed.
-
-=item *
-
-The locale tests could crash on Win32 due to a Windows bug, and
-separately due to the CRT throwing an exception if the locale name
-wasn't validly encoded in the current code page.
-
-For the second we now decode the locale name ourselves, and always
-decode it as UTF-8. [L<perl #133981|https://rt.perl.org/Ticket/Display.html?id=133981>]
-
-=item *
-
-F<t/op/magic.t> could fail if environment variables starting with
-C<FOO> already existed.
-
-=item *
+=item XXX-some-platform
 
-MYMALLOC (PERL_MALLOC) build has been fixed.
+XXX
 
 =back
 
-=item Solaris
-
-=over 4
-
-=item *
-
-C<Configure> will now find recent versions of the Oracle Developer Studio
-compiler, which are found under C</opt/developerstudio*>.
-
-=item *
-
-C<Configure> now uses the detected types for C<gethostby*> functions, allowing
-Perl to once again compile on certain configurations of Solaris.
-
-=back
+=head2 Discontinued Platforms
 
-=item VMS
+XXX List any platforms that this version of perl no longer compiles on.
 
 =over 4
 
-=item *
-
-With the release of the patch kit C99 V2.0, VSI has provided support for a
-number of previously-missing C99 features. On systems with that patch kit
-installed, Perl's configuration process will now detect the presence of the
-header C<stdint.h> and the following functions: C<fpclassify>, C<isblank>, C<isless>,
-C<llrint>, C<llrintl>, C<llround>, C<llroundl>, C<nearbyint>, C<round>, C<scalbn>,
-and C<scalbnl>.
-
-=item *
+=item XXX-some-platform
 
-C<-Duse64bitint> is now the default on VMS.
+XXX
 
 =back
 
-=item z/OS
+=head2 Platform-Specific Notes
 
-Perl 5.32 has been tested on z/OS 2.4, with the following caveats:
+XXX List any changes for specific platforms.  This could include configuration
+and compilation changes or changes in portability/compatibility.  However,
+changes within modules for platforms should generally be listed in the
+L</Modules and Pragmata> section.
 
 =over 4
 
-=item *
+=item XXX-some-platform
 
-Only static builds (the default) build reliably
-
-=item *
-
-When using locales, z/OS does not handle the C<LC_MESSAGES> category
-properly, so when compiling perl, you should add the following to your
-F<Configure> options
-
- ./Configure <other options> -Accflags=-DNO_LOCALE_MESSAGES
-
-=item *
-
-z/OS does not support locales with threads, so when compiling a threaded
-perl, you should add the following to your F<Configure> options
-
- ./Configure <other Configure options> -Accflags=-DNO_LOCALE
-
-=item *
-
-Some CPAN modules that are shipped with perl fail at least one of their
-self-tests.  These are:
-Archive::Tar,
-Config::Perl::V,
-CPAN::Meta,
-CPAN::Meta::YAML,
-Digest::MD5,
-Digest::SHA,
-Encode,
-ExtUtils::MakeMaker,
-ExtUtils::Manifest,
-HTTP::Tiny,
-IO::Compress,
-IPC::Cmd,
-JSON::PP,
-libnet,
-MIME::Base64,
-Module::Metadata,
-PerlIO::via-QuotedPrint,
-Pod::Checker,
-podlators,
-Pod::Simple,
-Socket,
-and Test::Harness.
-
-The causes of the failures range from the self-test itself is flawed,
-and the module actually works fine, up to the module doesn't work at all
-on EBCDIC platforms.
-
-=back
+XXX
 
 =back
 
 =head1 Internal Changes
 
-=over 4
-
-=item *
-
-C<savepvn>'s len parameter is now a C<Size_t> instead of an C<I32> since we
-can handle longer strings than 31 bits.
-
-=item *
-
-The lexer (C<Perl_yylex()> in F<toke.c>) was previously a single 4100-line
-function, relying heavily on C<goto> and a lot of widely-scoped local variables
-to do its work. It has now been pulled apart into a few dozen smaller static
-functions; the largest remaining chunk (C<yyl_word_or_keyword()>) is a little
-over 900 lines, and consists of a single C<switch> statement, all of whose
-C<case> groups are independent. This should be much easier to understand and
-maintain.
-
-=item *
-
-The OS-level signal handlers and type (Sighandler_t) used by the perl core
-were declared as having three parameters, but the OS was always told to
-call them with one argument. This has been fixed by declaring them to have
-one parameter. See the merge commit C<v5.31.5-346-g116e19abbf> for full
-details.
-
-=item *
-
-The code that handles C<tr///> has been extensively revised, fixing
-various bugs, especially when the source and/or replacement strings
-contain characters whose code points are above 255. Some of the bugs
-were undocumented, one being that under some circumstances (but not all)
-with C</s>, the squeezing was done based on the source, rather than the
-replacement. A documented bug that got fixed was
-[L<perl #125493|https://rt.perl.org/Ticket/Display.html?id=125493>].
+XXX Changes which affect the interface available to C<XS> code go here.  Other
+significant internal changes for future core maintainers should be noted as
+well.
 
-=item *
-
-A new macro for XS writers dealing with UTF-8-encoded Unicode strings
-has been created L<perlapi/C<UTF8_CHK_SKIP>> that is safer in the face
-of malformed UTF-8 input than L<perlapi/C<UTF8_SKIP>> (but not as safe
-as L<perlapi/C<UTF8_SAFE_SKIP>>). It won't read past a NUL character.
-It has been backported in L<Devel::PPPort> 3.55 and later.
-
-=item *
-
-Added the C<< PL_curstackinfo->si_cxsubix >> field. This records the stack index
-of the most recently pushed sub/format/eval context. It is set and restored
-automatically by C<cx_pushsub()>, C<cx_popsub()> etc., but would need to be
-manually managed if you do any unusual manipulation of the context stack.
-
-=item *
-
-Various macros dealing with character type classification and changing case
-where the input is encoded in UTF-8 now require an extra parameter to prevent
-potential reads beyond the end of the buffer. Use of these has generated a
-deprecation warning since Perl 5.26. Details are in
-L<perldeprecation/In XS code, use of various macros dealing with UTF-8.>
-
-=item *
-
-A new parser function L<parse_subsignature()|perlapi/parse_subsignature>
-allows a keyword plugin to parse a subroutine signature while C<use feature
-'signatures'> is in effect. This allows custom keywords to implement
-semantics similar to regular C<sub> declarations that include signatures.
-[L<perl #132474|https://rt.perl.org/Ticket/Display.html?id=132474>]
-
-=item *
-
-Since on some platforms we need to hold a mutex when temporarily
-switching locales, new macros (C<STORE_LC_NUMERIC_SET_TO_NEEDED_IN>,
-C<WITH_LC_NUMERIC_SET_TO_NEEDED> and C<WITH_LC_NUMERIC_SET_TO_NEEDED_IN>)
-have been added to make it easier to do this safely and efficiently
-as part of [L<perl #134172|https://rt.perl.org/Ticket/Display.html?id=134172>].
+[ List each change as an =item entry ]
 
-=item *
-
-The memory bookkeeping overhead for allocating an OP structure has been
-reduced by 8 bytes per OP on 64-bit systems.
-
-=item *
-
-L<eval_pv()|perlapi/eval_pv> no longer stringifies the exception when
-C<croak_on_error> is true. [L<perl #134175|https://rt.perl.org/Ticket/Display.html?id=134175>]
-
-=item *
-
-The PERL_DESTRUCT_LEVEL environment variable was formerly only honoured on perl
-binaries built with DEBUGGING support. It is now checked on all perl builds.
-Its normal use is to force perl to individually free every block of memory
-which it has allocated before exiting, which is useful when using automated
-leak detection tools such as valgrind.
-
-=item *
-
-The API eval_sv() now accepts a C<G_RETHROW> flag. If this flag is set and an
-exception is thrown while compiling or executing the supplied code, it will be
-rethrown, and eval_sv() will not return.
-[L<perl #134177|https://rt.perl.org/Ticket/Display.html?id=134177>]
-
-=item *
-
-As part of the fix for
-[L<perl #2754|https://rt.perl.org/Ticket/Display.html?id=2754>] perl_parse()
-now returns non-zero if exit(0) is called in a C<BEGIN>, C<UNITCHECK> or
-C<CHECK> block.
+=over 4
 
 =item *
 
-Most functions which recursively walked an op tree during compilation have been
-made non-recursive. This avoids SEGVs from stack overflow when the op tree is
-deeply nested, such as C<$n == 1 ? "one" : $n == 2 ? "two" : ....> (especially
-in code which is auto-generated).
-
-This is particularly noticeable where the code is compiled within a separate
-thread, as threads tend to have small stacks by default.
+XXX
 
 =back
 
 =head1 Selected Bug Fixes
 
-=over 4
-
-=item *
-
-Previously L<perlfunc/require> would only treat the special built-in
-SV C<&PL_sv_undef> as a value in C<%INC> as if a previous C<require>
-has failed, treating other undefined SVs as if the previous C<require>
-has succeeded. This could cause unexpected success from C<require>
-e.g., on C<local %INC = %INC;>. This has been fixed. [L<GH #17428|https://github.com/Perl/perl5/issues/17428>]
-
-=item *
-
-C<(?{...})> eval groups in regular expressions no longer unintentionally
-trigger "EVAL without pos change exceeded limit in regex" [L<GH #17490|https://github.com/Perl/perl5/issues/17490>].
-
-=item *
-
-C<(?[...])> extended bracketed character classes do not wrongly raise an
-error on some cases where a previously-compiled such class is
-interpolated into another. The heuristics previously used have been
-replaced by a reliable method, and hence the diagnostics generated have
-changed. See L</Diagnostics>.
-
-=item *
-
-The debug display (say by specifying C<-Dr> or S<C<use re>> (with
-appropriate options) of compiled Unicode property wildcard subpatterns no
-longer has extraneous output.
-
-=item *
-
-Fix an assertion failure in the regular expression engine.
-[L<GH #17372|https://github.com/Perl/perl5/issues/17372>]
-
-=item *
-
-Fix coredump in pp_hot.c after C<B::UNOP_AUX::aux_list()>.
-[L<GH #17301|https://github.com/Perl/perl5/issues/17301>]
-
-=item *
-
-Loading IO is now threadsafe.
-[L<GH #14816|https://github.com/Perl/perl5/issues/14816>]
-
-=item *
-
-C<\p{user-defined}> overrides official Unicode [L<GH #17025|https://github.com/Perl/perl5/issues/17025>]
-
-Prior to this patch, the override was only sometimes in effect.
-
-=item *
-
-Properly handle filled C</il> regnodes and multi-char folds
-
-=item *
-
-Compilation error during make minitest [L<GH #17293|https://github.com/Perl/perl5/issues/17293>]
-
-=item *
-
-Move the implementation of C<%->, C<%+> into core.
-
-=item *
-
-Read beyond buffer in C<grok_inf_nan> [L<GH #17370|https://github.com/Perl/perl5/issues/17370>]
-
-=item *
-
-Workaround glibc bug with C<LC_MESSAGES> [L<GH #17081|https://github.com/Perl/perl5/issues/17081>]
-
-=item *
-
-C<printf()> or C<sprintf()> with the C<%n> format could cause a panic on
-debugging builds, or report an incorrectly cached length value when
-producing C<SVfUTF8> flagged strings. [L<GH #17221|https://github.com/Perl/perl5/issues/17221>]
-
-=item *
-
-The tokenizer has been extensively refactored.
-[L<GH #17241|https://github.com/Perl/perl5/issues/17241>]
-[L<GH #17189|https://github.com/Perl/perl5/issues/17189>]
-
-=item *
-
-C<use strict "subs"> is now enforced for bareword constants optimized
-into a C<multiconcat> operator. [L<GH #17254|https://github.com/Perl/perl5/issues/17254>]
-
-=item *
-
-A memory leak in regular expression patterns has been fixed. [L<GH #17218|https://github.com/Perl/perl5/issues/17218>]
-
-=item *
-
-Perl no longer treats strings starting with "0x" or "0b" as hex or
-binary numbers respectively when converting a string to a number.
-This reverts a change in behaviour inadvertently introduced in perl
-5.30.0 intended to improve precision when converting a string to a
-floating point number. [L<perl #134230|https://rt.perl.org/Ticket/Display.html?id=134230>]
-
-=item *
-
-Matching a non-C<SVf_UTF8> string against a regular expression
-containing unicode literals could leak a SV on each match attempt.
-[L<perl #134390|https://rt.perl.org/Ticket/Display.html?id=134390>]
-
-=item *
-
-Overloads for octal and binary floating point literals were always
-passed a string with a C<0x> prefix instead of the appropriate C<0> or
-C<0b> prefix. [L<perl #125557|https://rt.perl.org/Ticket/Display.html?id=125557>]
-
-=item *
-
-C<< $@ = 100; die; >> now correctly propagates the 100 as an exception
-instead of ignoring it. [L<perl #134291|https://rt.perl.org/Ticket/Display.html?id=134291>]
-
-=item *
-
-C<< 0 0x@ >> no longer asserts in S_no_op(). [L<perl #134310|https://rt.perl.org/Ticket/Display.html?id=134310>]
-
-=item *
-
-Exceptions thrown while C<$@> is read-only could result in infinite
-recursion as perl tried to update C<$@>, which throws another
-exception, resulting in a stack overflow. Perl now replaces C<$@>
-with a copy if it's not a simple writable SV. [L<perl #134266|https://rt.perl.org/Ticket/Display.html?id=134266>]
-
-=item *
-
-Setting C<$)> now properly sets supplementary group ids if you have
-the necessary privileges. [L<perl #134169|https://rt.perl.org/Ticket/Display.html?id=134169>]
-
-=item *
+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>.
 
-close() on a pipe now preemptively clears the PerlIO object from the
-IO SV. This prevents a second attempt to close the already closed
-PerlIO object if a signal handler calls die() or exit() while close()
-is waiting for the child process to complete. [L<perl #122112|https://rt.perl.org/Ticket/Display.html?id=122112>]
+[ List each fix as an =item entry ]
 
-=item *
-
-C<< sprintf("%.*a", -10000, $x) >> would cause a buffer overflow due
-to mishandling of the negative precision value. [L<perl #134008|https://rt.perl.org/Ticket/Display.html?id=134008>]
-
-=item *
-
-scalar() on a reference could cause an erroneous assertion failure
-during compilation. [L<perl #134045|https://rt.perl.org/Ticket/Display.html?id=134045>]
-
-=item *
-
-C<%{^CAPTURE_ALL}> is now an alias to C<%-> as documented, rather than
-incorrectly an alias for C<%+>. [L<perl #131867|https://rt.perl.org/Ticket/Display.html?id=131867>]
-
-=item *
-
-C<%{^CAPTURE}> didn't work if C<@{^CAPTURE}> was mentioned first.
-Similarly for C<%{^CAPTURE_ALL}> and C<@{^CAPTURE_ALL}>, though
-C<@{^CAPTURE_ALL}> currently isn't used. [L<perl #134193|https://rt.perl.org/Ticket/Display.html?id=134193>]
-
-=item *
-
-Extraordinarily large (over 2GB) floating point format widths could
-cause an integer overflow in the underlying call to snprintf(),
-resulting in an assertion. Formatted floating point widths are now
-limited to the range of int, the return value of snprintf(). [L<perl
-#133913|https://rt.perl.org/Ticket/Display.html?id=133913>]
-
-=item *
-
-Parsing the following constructs within a sub-parse (such as with
-C<"${code here}"> or C<s/.../code here/e>) has changed to match how
-they're parsed normally:
-
-=over
-
-=item *
-
-C<print $fh ...> no longer produces a syntax error.
-
-=item *
-
-Code like C<s/.../ ${time} /e> now properly produces an "Ambiguous use
-of ${time} resolved to $time at ..." warning when warnings are enabled.
-
-=item *
-
-C<@x {"a"}> (with the space) in a sub-parse now properly produces a
-"better written as" warning when warnings are enabled.
+=over 4
 
 =item *
 
-Attributes can now be used in a sub-parse.
-[L<perl #133850|https://rt.perl.org/Ticket/Display.html?id=133850>]
+XXX
 
 =back
 
-=item *
-
-Incomplete hex and binary literals like C<0x> and C<0b> are now
-treated as if the C<x> or C<b> is part of the next token. [L<perl
-#134125|https://rt.perl.org/Ticket/Display.html?id=134125>]
-
-=item *
-
-A spurious C<)> in a subparse, such as in C<s/.../code here/e> or
-C<"...${code here}">, no longer confuses the parser.
-
-Previously a subparse was bracketed with generated C<(> and C<)>
-tokens, so a spurious C<)> would close the construct without doing the
-normal subparse clean up, confusing the parser and possible causing an
-assertion failure.
-
-Such constructs are now surrounded by artificial tokens that can't be
-included in the source. [L<perl #130585|https://rt.perl.org/Ticket/Display.html?id=130585>]
-
-=item *
-
-Reference assignment of a sub, such as C<\&foo = \&bar;>, silently did
-nothing in the C<main::> package. [L<perl #134072|https://rt.perl.org/Ticket/Display.html?id=134072>]
-
-=item *
-
-sv_gets() now recovers better if the target SV is modified by a signal
-handler. [L<perl #134035|https://rt.perl.org/Ticket/Display.html?id=134035>]
+=head1 Known Problems
 
-=item *
+XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
+tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
+platform specific bugs also go here.
 
-C<readline @foo> now evaluates C<@foo> in scalar context. Previously
-it would be evaluated in list context, and since readline() pops only
-one argument from the stack, the stack could underflow, or be left
-with unexpected values on the stack. [L<perl #133989|https://rt.perl.org/Ticket/Display.html?id=133989>]
+[ List each fix as an =item entry ]
 
-=item *
-
-Parsing incomplete hex or binary literals was changed in 5.31.1 to treat such a
-literal as just the 0, leaving the following C<x> or C<b> to be parsed as part
-of the next token. This could lead to some silent changes in behaviour, so now
-incomplete hex or binary literals produce a fatal error.
-[L<perl #134125|https://rt.perl.org/Ticket/Display.html?id=134125>]
+=over 4
 
 =item *
 
-eval_pv()'s I<croak_on_error> flag will now throw even if the exception is a
-false overloaded value.
-[L<perl #134177|https://rt.perl.org/Ticket/Display.html?id=134177>]
+XXX
 
-=item *
-
-C<INIT> blocks and the program itself are no longer run if exit(0) is called
-within a C<BEGIN>, C<UNITCHECK> or C<CHECK> block.
-[L<perl #2754|https://rt.perl.org/Ticket/Display.html?id=2754>]
+=back
 
-=item *
+=head1 Errata From Previous Releases
 
-C<< open my $fh, ">>+", undef >> now opens the temporary file in append mode:
-writes will seek to the end of file before writing.
-[L<perl #134221|https://rt.perl.org/Ticket/Display.html?id=134221>]
+=over 4
 
 =item *
 
-Fixed a SEGV when searching for the source of an uninitialized value warning on
-an op whose subtree includes an OP_MULTIDEREF.
-[L<perl #134275|https://rt.perl.org/Ticket/Display.html?id=134275>]
+XXX Add anything here that we forgot to add, or were mistaken about, in
+the perldelta of a previous release.
 
 =back
 
 =head1 Obituary
 
-Jeff Goff (JGOFF or DrForr), an integral part of the Perl and Raku
-communities and a dear friend to all of us, has passed away on March
-13th, 2020. DrForr was a prominent member of the communities, attending
-and speaking at countless events, contributing to numerous projects,
-and assisting and helping in any way he could.
-
-His passing leaves a hole in our hearts and in our communities and he
-will be sorely missed.
+XXX If any significant core contributor or member of the CPAN community has
+died, add a short obituary here.
 
 =head1 Acknowledgements
 
-Perl 5.32.0 represents approximately 13 months of development since Perl
-5.30.0 and contains approximately 220,000 lines of changes across 1,800
-files from 89 authors.
-
-Excluding auto-generated files, documentation and release tools, there were
-approximately 140,000 lines of changes to 880 .pm, .t, .c and .h files.
-
-Perl continues to flourish into its fourth decade thanks to a vibrant
-community of users and developers. The following people are known to have
-contributed the improvements that became Perl 5.32.0:
-
-Aaron Crane, Alberto Simões, Alexandr Savca, Andreas König, Andrew Fresh,
-Andy Dougherty, Ask Bjørn Hansen, Atsushi Sugawara, Bernhard M. Wiedemann,
-brian d foy, Bryan Stenson, Chad Granum, Chase Whitener, Chris 'BinGOs'
-Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, Dan Book, Daniel
-Dragan, Dan Kogai, Dave Cross, Dave Rolsky, David Cantrell, David Mitchell,
-Dominic Hargreaves, E. Choroba, Felipe Gasper, Florian Weimer, Graham Knop,
-Håkon Hægland, Hauke D, H.Merijn Brand, Hugo van der Sanden, Ichinose
-Shogo, James E Keenan, Jason McIntosh, Jerome Duval, Johan Vromans, John
-Lightsey, John Paul Adrian Glaubitz, Kang-min Liu, Karen Etheridge, Karl
-Williamson, Leon Timmermans, Manuel Mausz, Marc Green, Matthew Horsfall,
-Matt Turner, Max Maischein, Michael Haardt, Nicholas Clark, Nicolas R., Niko
-Tyni, Pali, Paul Evans, Paul Johnson, Paul Marquess, Peter Eisentraut, Peter
-John Acklam, Peter Oliver, Petr Písař, Renee Baecker, Ricardo Signes,
-Richard Leach, Russ Allbery, Samuel Smith, Santtu Ojanperä, Sawyer X,
-Sergey Aleynikov, Sergiy Borodych, Shirakata Kentaro, Shlomi Fish, Sisyphus,
-Slaven Rezic, Smylers, Stefan Seifert, Steve Hay, Steve Peters, Svyatoslav,
-Thibault Duponchelle, Todd Rinaldo, Tomasz Konojacki, Tom Hukins, Tony Cook,
-Unicode Consortium, VanL, Vickenty Fesunov, Vitali Peil, Yves Orton, Zefram.
-
-The list above is almost certainly incomplete as it is automatically
-generated from version control history. In particular, it does not include
-the names of the (very much appreciated) contributors who reported issues to
-the Perl bug tracker.
-
-Many of the changes included in this version originated in the CPAN modules
-included in Perl's core. We're grateful to the entire CPAN community for
-helping Perl to flourish.
-
-For a more complete list of all of Perl's historical contributors, please
-see the F<AUTHORS> file in the Perl source distribution.
+XXX Generate this with:
+
+  perl Porting/acknowledgements.pl v5.32.0..HEAD
 
 =head1 Reporting Bugs
 
 If you find what you think is a bug, you might check the perl bug database
-at L<https://github.com/Perl/perl5/issues>. There may also be information at
+at L<https://github.com/Perl/perl5/issues>.  There may also be information at
 L<http://www.perl.org/>, the Perl Home Page.
 
 If you believe you have an unreported bug, please open an issue at
-L<https://github.com/Perl/perl5/issues>. Be sure to trim your bug down to a
+L<https://github.com/Perl/perl5/issues>.  Be sure to trim your bug down to a
 tiny but sufficient test case.
 
 If the bug you are reporting has security implications which make it
diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template
index 0ba7c3d159..0c5f1ebd56 100644
--- a/vms/descrip_mms.template
+++ b/vms/descrip_mms.template
@@ -313,7 +313,7 @@ utils : $(utils1) $(utils2) $(utils3) $(utils4) $(utils5)
 extra.pods : miniperl
 	@ @extra_pods.com
 
-PERLDELTA_CURRENT = [.pod]perl5320delta.pod
+PERLDELTA_CURRENT = [.pod]perl5321delta.pod
 
 $(PERLDELTA_CURRENT) : [.pod]perldelta.pod
 	Copy/NoConfirm/Log $(MMS$SOURCE) $(PERLDELTA_CURRENT)
diff --git a/win32/GNUmakefile b/win32/GNUmakefile
index 0aac005e85..d0656b7da9 100644
--- a/win32/GNUmakefile
+++ b/win32/GNUmakefile
@@ -1745,7 +1745,7 @@ utils: $(HAVEMINIPERL) ..\utils\Makefile
 	copy ..\README.tw       ..\pod\perltw.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5320delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5321delta.pod
 	$(MINIPERL) -I..\lib $(PL2BAT) $(UTILS)
 	$(MINIPERL) -I..\lib ..\autodoc.pl ..
 	$(MINIPERL) -I..\lib ..\pod\perlmodlib.PL -q ..
@@ -1843,7 +1843,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-cd $(PODDIR) && del /f *.html *.bat roffitall \
-	    perl5320delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+	    perl5321delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
 	    perlapi.pod perlbs2000.pod perlcn.pod perlcygwin.pod \
 	    perldos.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \
 	    perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \
diff --git a/win32/Makefile b/win32/Makefile
index 2ddcf3a81a..863945a330 100644
--- a/win32/Makefile
+++ b/win32/Makefile
@@ -1265,7 +1265,7 @@ utils: $(PERLEXE) ..\utils\Makefile
 	copy ..\README.tw       ..\pod\perltw.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5320delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5321delta.pod
 	cd ..\win32
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(MINIPERL) -I..\lib ..\autodoc.pl ..
@@ -1364,7 +1364,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-cd $(PODDIR) && del /f *.html *.bat roffitall \
-	    perl5320delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+	    perl5321delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
 	    perlapi.pod perlbs2000.pod perlcn.pod perlcygwin.pod \
 	    perldos.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \
 	    perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \
diff --git a/win32/makefile.mk b/win32/makefile.mk
index 7ea7b53328..c7124a3f87 100644
--- a/win32/makefile.mk
+++ b/win32/makefile.mk
@@ -1664,7 +1664,7 @@ utils: $(HAVEMINIPERL) ..\utils\Makefile
 	copy ..\README.tw       ..\pod\perltw.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5320delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5321delta.pod
 	$(MINIPERL) -I..\lib $(PL2BAT) $(UTILS)
 	$(MINIPERL) -I..\lib ..\autodoc.pl ..
 	$(MINIPERL) -I..\lib ..\pod\perlmodlib.PL -q ..
@@ -1762,7 +1762,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-cd $(PODDIR) && del /f *.html *.bat roffitall \
-	    perl5320delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+	    perl5321delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
 	    perlapi.pod perlbs2000.pod perlcn.pod perlcygwin.pod \
 	    perldos.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \
 	    perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \
diff --git a/win32/pod.mak b/win32/pod.mak
index 81d87446b4..9872a231bb 100644
--- a/win32/pod.mak
+++ b/win32/pod.mak
@@ -63,6 +63,7 @@ POD = perl.pod	\
 	perl5302delta.pod	\
 	perl5303delta.pod	\
 	perl5320delta.pod	\
+	perl5321delta.pod	\
 	perl561delta.pod	\
 	perl56delta.pod	\
 	perl581delta.pod	\
@@ -221,6 +222,7 @@ MAN = perl.man	\
 	perl5302delta.man	\
 	perl5303delta.man	\
 	perl5320delta.man	\
+	perl5321delta.man	\
 	perl561delta.man	\
 	perl56delta.man	\
 	perl581delta.man	\
@@ -379,6 +381,7 @@ HTML = perl.html	\
 	perl5302delta.html	\
 	perl5303delta.html	\
 	perl5320delta.html	\
+	perl5321delta.html	\
 	perl561delta.html	\
 	perl56delta.html	\
 	perl581delta.html	\
@@ -537,6 +540,7 @@ TEX = perl.tex	\
 	perl5302delta.tex	\
 	perl5303delta.tex	\
 	perl5320delta.tex	\
+	perl5321delta.tex	\
 	perl561delta.tex	\
 	perl56delta.tex	\
 	perl581delta.tex	\