[ List each enhancement as a =head2 entry ]
+=head2 faster array and hash lookups
+
+Array and hash lookups (especially nested ones) that use only constants
+or simple variables as keys, are now considerably faster. See
+L</Internal Changes> for more details.
+
+=head2 C<fileno> now works on directory handles
+
+When the relevant support is available in the operating system, the
+C<fileno> builtin now works on directory handles, yielding the
+underlying file descriptor in the same way as for filehandles. On
+operating systems without such support, C<fileno> on a directory handle
+continues to return the undefined value, as before, but also sets C<$!> to
+indicate that the operation is not supported.
+
+Currently, this uses either a C<dd_fd> member in the OS C<DIR>
+structure, or a dirfd(3) function as specified by POSIX.1-2008.
+
=head1 Security
XXX Any security-related notices go here. In particular, any security
[ List each incompatible change as a =head2 entry ]
+=head2 C<&> and C<\&> prototypes accepts only subs
+
+The C<&> prototype character now accepts only anonymous subs (C<sub {...}>)
+and things beginning with C<\&>. Formerly it erroneously also allowed
+C<undef> and references to array, hashes, and lists. [perl #4539]
+[perl #123062]
+
+The C<\&> prototype was allowing subroutine calls, whereas now it only
+allows subroutines. C<&foo> is permitted. C<&foo()> and C<foo()> are not.
+[perl #77860]
+
+=head2 C<use encoding> is now lexical
+
+The L<encoding> pragma's effect is now limited to lexical scope. This
+pragma is deprecated, but in the meantime, it could adversely affect
+unrelated modules that are included in the same program.
+
+=head2 List slices returning empty lists
+
+List slices return an empty list now only if the original list was empty
+(or if there are no indices). Formerly, a list slice would return an empty
+list if all indices fell outside the original list. [perl #114498]
+
=head1 Deprecations
XXX Any deprecated features, syntax, modules etc. should be listed here.
=item *
-XXX
+Win32 Perl uses 8 KB less of per-process memory than before for every perl
+process of this version. This data is now memory mapped from disk and shared
+between perl processes from the same perl binary.
+
+=item *
+
+If method and class names are known at compile time, hashes are precomputed
+to speed up run-time method lookup. Also, compound method names like
+C<SUPER::new> are parsed at compile time, to save having to parse them at
+run time.
=back
=item *
-L<XXX> has been upgraded from version A.xx to B.yy.
+L<B> has been upgraded from version 1.53 to 1.54.
+
+Nulled COPs are now of class C<B::COP>, rather than C<B::OP>.
+
+B::REGEXP objects now provide a C<qr_anoncv> method for accessing the
+implicit CV associated with C<qr//> things containing code blocks.
+
+B::PMOP now provides a C<pmregexp> method returning a B::REGEXP object.
+
+Two new classes, B::PADNAME and B::PADNAMELIST, have been introduced.
+
+=item *
+
+L<B::Deparse> has been upgraded from version 1.30 to 1.31.
+
+BEGIN blocks at the end of the enclosing scope are now deparsed in the
+right place. [perl #77452]
+
+BEGIN blocks were sometimes deparsed as __ANON__, but are now always called
+BEGIN.
+
+Lexical subroutines are now fully deparsed. [perl #116553]
+
+Deparsing of C<$lexical =~ //> was accidentally broken in 1.30 (perl
+5.21.6), omitting the C<$lexical =~>, but has now been fixed.
+
+C<Anything =~ y///r> with C</r> no longer omits the left-hand operand.
+
+The op trees that make up regexp code blocks are now deparsed for real.
+Formerly, the original string that made up the regular expression was used.
+That caused problems with C<qr/(?{<<heredoc})/> and multiline code blocks,
+which were deparsed incorrectly. [perl #123217] [perl #115256]
+
+C<$;> at the end of a statement no longer loses its semicolon.
+[perl #123357]
+
+Some cases of subroutine declarations stored in the stash in shorthand form
+were being omitted.
+
+Non-ASCII characters are now consistently escaped in strings, instead of
+some of the time. (There are still outstanding problems with regular
+expressions and identifiers that have not been fixed.)
+
+When prototype sub calls are deparsed with C<&> (e.g., under the B<-P>
+option), C<scalar> is now added where appropriate, to force the scalar
+context implied by the prototype.
+
+C<require(foo())>, C<do(foo())>, C<goto(foo())> and similar constructs with
+loop controls are now deparsed correctly. The outer parentheses are not
+optional.
+
+Whitespace is no longer escaped in regular expressions, because it was
+getting erroneously escaped within C<(?x:...)> sections.
+
+C<sub foo { foo() }> is now deparsed with those mandatory parentheses.
+
+C</@array/> is now deparsed as a regular expression, and not just
+C<@array>.
+
+C</@{-}/>, C</@{+}/> and C<$#{1}> are now deparsed with the braces, which
+are mandatory in these cases.
+
+In deparsing feature bundles, B::Deparse was emitting C<no feature;> first
+instead of C<no feature ':all';>. This has been fixed.
+
+C<chdir FH> is now deparsed without quotation marks.
+
+C<\my @a> is now deparsed without parentheses. (Parenthese would flatten
+the array.)
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded from version 3.26 to 3.27.
+
+Only declare C<file> unused if we actually define it.
+
+Improve generated C<RETVAL> code generation to avoid repeated
+references to C<ST(0)>. [perl #123278]
+
+Broaden and document the C</OBJ$/> to C</REF$/> typemap optimization
+for the C<DESTROY> method. [perl #123418]
+
+=item *
+
+The PathTools module collection has been upgraded from 3.52 to 3.53.
+
+Don't turn leading C<//> into C</> on Cygwin. [perl #122635]
+
+=item *
+
+L<Locale::Maketext> has been upgraded from version 1.25 to 1.26.
+
+=item *
+
+L<XSLoader> has been upgraded from version 0.19 to 0.20
+
+Don't test twice for bootstrap file.
=back
=item *
-XXX Describe change here
+"Variable %s will not stay shared" has been changed to say "Subroutine"
+when it is actually a lexical sub that will not stay shared.
=back
=head2 Platform-Specific Notes
-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.
+=head3 Win32
-=over 4
+=over
-=item XXX-some-platform
+=item *
-XXX
+Intel C builds are now always built with C99 mode on.
=back
=item *
-XXX
+The PADNAME and PADNAMELIST types are now separate types, and no longer
+simply aliases for SV and AV. [perl #123223]
+
+=item *
+
+Pad names are now always UTF8. The C<PadnameUTF8> macro always returns
+true. Previously, this was effectively the case already, but any support
+for two different internal representations of pad names has now been
+removed.
+
+=item *
+
+The C<OP_SIBLING> and C<OP_HAS_SIBLING> macros added in an earlier 5.21.x
+release have been renamed C<OpSIBLING> and C<OpHAS_SIBLING>, following the
+existing convention.
+
+=item *
+
+A new op class, C<UNOP_AUX>, has been added. This is a subclass of
+C<UNOP> with an C<op_aux> field added, which points to an array of unions
+of C<UV>, C<SV*> etc. It is intended for where an op needs to store more data
+than a simple C<op_sv> or whatever. Currently the only op of this type is
+C<OP_MULTIDEREF> (see below).
+
+=item *
+
+A new op has been added, C<OP_MULTIDEREF>, which performs one or more
+nested array and hash lookups where the key is a constant or simple
+variable. For example the expression C<$a[0]{$k}[$i]>, which previously
+involved ten C<rv2Xv>, C<Xelem>, C<gvsv> and C<const> ops is now performed
+by a single C<multideref> op. It can also handle C<local>, C<exists> and
+C<delete>. A non-simple index expression, such as C<[$i+1]> is still done
+using C<aelem/helem>, and single-level array lookup with a small constant
+index is still done using C<aelemfast>.
=back
=item *
-XXX
+On Win32, restoring in a child pseudo-process a variable that was
+C<local()>ed in a parent pseudo-process before the C<fork> happened caused
+memory corruption and a crash in the child pseudo-process (and therefore OS
+process). [perl #40565]
=item *
-The L<encoding> pragma's effect is now limited to lexical scope. This
-pragma is deprecated, but in the meantime, it could adversely affect
-unrelated modules that are included in the same program.
+Calling C<write> on a format with a C<^**> field could produce a panic
+in sv_chop() if there were insufficient arguments or if the variable
+used to fill the field was empty. [perl #123245]
+
+=item *
+
+Non-ASCII lexical sub names (use in error messages) on longer have extra
+junk on the end.
+
+=item *
+
+The C<\@> subroutine prototype no longer flattens parenthesized arrays
+(taking a reference to each element), but takes a reference to the array
+itself. [perl #47363]
+
+=item *
+
+A block containing nothing except a C-style C<for> loop could corrupt the
+stack, causing lists outside the block to lose elements or have elements
+overwritten. This could happen with C<map { for(...){...} } ...> and with
+lists containing C<do { for(...){...} }>. [perl #123286]
+
+=item *
+
+C<scalar()> now propagates lvalue context, so that
+C<for(scalar($#foo)) { ... }> can modify C<$#foo> through C<$_>.
+
+=item *
+
+C<qr/@array(?{block})/> no longer dies with "Bizarre copy of ARRAY".
+[#123344]
+
+=item *
+
+C<eval '$variable'> in nested named subroutines would sometimes look up a
+global variable even with a lexical variable in scope.
+
+In perl 5.20.0, C<sort CORE::fake> where 'fake' is anything other than a
+keyword started chopping of the last 6 characters and treating the result
+as a sort sub name. The previous behaviour of treating "CORE::fake" as a
+sort sub name has been restored. [perl #123410]
+
+=item *
+
+Outside of C<use utf8>, a single-character Latin-1 lexical variable is
+disallowed. The error message for it, "Can't use global $foo...", was
+giving garbage instead of the variable name.
=back