New perldelta for v5.21.7

10 files changed, 904 insertions, 482 deletions

diff --git a/MANIFEST b/MANIFEST
index 5faa395c1a..d1b2c7c807 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4586,6 +4586,7 @@ pod/perl5212delta.pod		Perl changes in version 5.21.2
 pod/perl5213delta.pod		Perl changes in version 5.21.3
 pod/perl5214delta.pod		Perl changes in version 5.21.4
 pod/perl5215delta.pod		Perl changes in version 5.21.5
+pod/perl5216delta.pod		Perl changes in version 5.21.6
 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 f3fea9a5e6..56f47a3188 100755
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -489,7 +489,7 @@ mini_obj = $(minindt_obj) $(MINIDTRACE_O)
 ndt_obj = $(obj0) $(obj1) $(obj2) $(obj3) $(ARCHOBJS)
 obj = $(ndt_obj) $(DTRACE_O)
 
-perltoc_pod_prereqs = extra.pods pod/perl5216delta.pod pod/perlapi.pod pod/perlintern.pod pod/perlmodlib.pod pod/perluniprops.pod
+perltoc_pod_prereqs = extra.pods pod/perl5217delta.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
 
@@ -1012,9 +1012,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/perl5216delta.pod: pod/perldelta.pod
-	$(RMS) pod/perl5216delta.pod
-	$(LNS) perldelta.pod pod/perl5216delta.pod
+pod/perl5217delta.pod: pod/perldelta.pod
+	$(RMS) pod/perl5217delta.pod
+	$(LNS) perldelta.pod pod/perl5217delta.pod
 
 extra.pods: $(MINIPERL_EXE)
 	-@test ! -f extra.pods || rm -f `cat extra.pods`
diff --git a/pod/.gitignore b/pod/.gitignore
index e814846ea2..b8f74a6479 100644
--- a/pod/.gitignore
+++ b/pod/.gitignore
@@ -53,7 +53,7 @@
 /roffitall
 
 # generated
-/perl5216delta.pod
+/perl5217delta.pod
 /perlapi.pod
 /perlintern.pod
 *.html
diff --git a/pod/perl.pod b/pod/perl.pod
index 6b2c93de6a..13647fda58 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -179,6 +179,7 @@ aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
 
     perlhist		Perl history records
     perldelta		Perl changes since previous version
+    perl5216delta Perl changes in version 5.21.6
     perl5215delta Perl changes in version 5.21.5
     perl5214delta Perl changes in version 5.21.4
     perl5213delta Perl changes in version 5.21.3
diff --git a/pod/perl5216delta.pod b/pod/perl5216delta.pod
new file mode 100644
index 0000000000..f995285c5f
--- /dev/null
+++ b/pod/perl5216delta.pod
@@ -0,0 +1,712 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5216delta - what is new for perl v5.21.6
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.21.5 release and the 5.21.6
+release.
+
+If you are upgrading from an earlier release such as 5.21.4, first read
+L<perl5215delta>, which describes differences between 5.21.4 and 5.21.5.
+
+=head1 Core Enhancements
+
+=head2 List form of pipe open implemented for Win32
+
+The list form of pipe:
+
+  open my $fh, "-|", "program", @arguments;
+
+is now implemented on Win32.  It has the same limitations as C<system
+LIST> on Win32, since the Win32 API doesn't accept program arguments
+as a list.
+
+=head2 Assignment to list repetition
+
+C<(...) x ...> can now be used within a list that is assigned to, as long
+as the left-hand side is a valid lvalue.  This allows C<(undef,undef,$foo)
+= that_function()> to be written as C<((undef)x2, $foo) = that_function()>.
+
+=head2 C<close> now sets C<$!>
+
+When an I/O error occurs, the fact that there has been an error is recorded
+in the handle.  C<close> returns false for such a handle.  Previously, the
+value of C<$!> would be untouched by C<close>, so the common convention of
+writing C<close $fh or die $!> did not work reliably.  Now the handle
+records the value of C<$!>, too, and C<close> restores it.
+
+=head1 Deprecations
+
+=head2 Use of non-graphic characters in single-character variable names
+
+The syntax for single-character variable names is more lenient than
+for longer variable names, allowing the one-character name to be a
+punctuation character or even invisible (a non-graphic).  Perl v5.20
+deprecated the ASCII-range controls as such a name.  Now, all
+non-graphic characters that formerly were allowed are deprecated.
+The practical effect of this occurs only when not under C<S<"use
+utf8">>, and affects just the C1 controls (code points 0x80 through
+0xFF), NO-BREAK SPACE, and SOFT HYPHEN.
+
+=head2 Inlining of C<sub () { $var }> with observable side-effects
+
+In many cases Perl makes sub () { $var } into an inlinable constant
+subroutine, capturing the value of $var at the time the C<sub> expression
+is evaluated.  This can break the closure behaviour in those cases where
+$var is subsequently modified.  The subroutine won't return the new value.
+
+This usage is now deprecated in those cases where the variable could be
+modified elsewhere.  Perl detects those cases and emits a deprecation
+warning.  Such code will likely change in the future and stop producing a
+constant.
+
+If your variable is only modified in the place where it is declared, then
+Perl will continue to make the sub inlinable with no warnings.
+
+    sub make_constant {
+        my $var = shift;
+        return sub () { $var }; # fine
+    }
+
+    sub make_constant_deprecated {
+        my $var;
+        $var = shift;
+        return sub () { $var }; # deprecated
+    }
+
+    sub make_constant_deprecated2 {
+        my $var = shift;
+        log_that_value($var); # could modify $var
+        return sub () { $var }; # deprecated
+    }
+
+In the second example above, detecting that $var is assigned to only once
+is too hard to detect.  That it happens in a spot other than the C<my>
+declaration is enough for Perl to find it suspicious.
+
+This deprecation warning happens only for a simple variable for the body of
+the sub.  (A C<BEGIN> block or C<use> statement inside the sub is ignored,
+because it does not become part of the sub's body.)  For more complex
+cases, such as C<sub () { do_something() if 0; $var }> the behaviour has
+changed such that inlining does not happen if the variable is modifiable
+elsewhere.  Such cases should be rare.
+
+=head1 Performance Enhancements
+
+=over 4
+
+=item *
+
+C<(...)x1>, C<("constant")x0> and C<($scalar)x0> are now optimised in list
+context.  If the right-hand argument is a constant 1, the repetition
+operator disappears.  If the right-hand argument is a constant 0, the whole
+expressions is optimised to the empty list, so long as the left-hand
+argument is a simple scalar or constant.  C<(foo())x0> is not optimised.
+
+=item *
+
+C<substr> assignment is now optimised into 4-argument C<substr> at the end
+of a subroutine (or as the argument to C<return>).  Previously, this
+optimisation only happened in void context.
+
+=item *
+
+Assignment to lexical variables is often optimised away.  For instance, in
+C<$lexical = chr $foo>, the C<chr> operator writes directly to the lexical
+variable instead of returning a value that gets copied.  This optimisation
+has been extended to C<split>, C<x> and C<vec> on the right-hand side.  It
+has also been made to work with state variable initialization.
+
+=item *
+
+In "\L...", "\Q...", etc., the extra "stringify" op is now optimised away,
+making these just as fast as C<lcfirst>, C<quotemeta>, etc.
+
+=item *
+
+Assignment to an empty list is now sometimes faster.  In particular, it
+never calls C<FETCH> on tied arguments on the right-hand side, whereas it
+used to sometimes.
+
+=back
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<B> has been upgraded from version 1.52 to 1.53.
+
+=item *
+
+L<B::Concise> has been upgraded from version 0.994 to 0.995.
+
+=item *
+
+L<B::Deparse> has been upgraded from version 1.29 to 1.30.
+
+It now deparses C<+sub : attr { ... }> correctly at the start of a
+statement.  Without the initial C<+>, C<sub> would be a statement label.
+
+C<BEGIN> blocks are now emitted in the right place most of the time, but
+the change unfortunately introduced a regression, in that C<BEGIN> blocks
+occurring just before the end of the enclosing block may appear below it
+instead.  So this change may need to be reverted if it cannot be fixed
+before Perl 5.22.  [perl #77452]
+
+B::Deparse no longer puts erroneous C<local> here and there, such as for
+C<LIST = tr/a//d>.  [perl #119815]
+
+Adjacent C<use> statements are no longer accidentally nested if one
+contains a C<do> block.  [perl #115066]
+
+=item *
+
+L<B::Op_private> has been upgraded from version 5.021005 to 5.021006.
+
+It now includes a hash named C<%ops_using>, list all op types that use a
+particular private flag.
+
+=item *
+
+L<CPAN::Meta> has been upgraded from version 2.142690 to 2.143240.
+
+=item *
+
+L<CPAN::Meta::Requirements> has been upgraded from version 2.128 to 2.130.
+
+=item *
+
+L<Devel::Peek> has been upgraded from version 1.18 to 1.19.
+
+=item *
+
+L<Digest::SHA> has been upgraded from version 5.92 to 5.93.
+
+=item *
+
+L<DynaLoader> has been upgraded from version 1.27 to 1.28.
+
+=item *
+
+L<Encode> has been upgraded from version 2.62 to 2.64.
+
+=item *
+
+L<experimental> has been upgraded from version 0.012 to 0.013.
+
+=item *
+
+L<Exporter> has been upgraded from version 5.71 to 5.72.
+
+=item *
+
+L<ExtUtils::MakeMaker> has been upgraded from version 6.98 to 7.02.
+
+=item *
+
+L<ExtUtils::Manifest> has been upgraded from version 1.68 to 1.69.
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded from version 3.25 to 3.26.
+
+=item *
+
+L<HTTP::Tiny> has been upgraded from version 0.050 to 0.051.
+
+=item *
+
+L<I18N::Langinfo> has been upgraded from version 0.11 to 0.12.
+
+=item *
+
+L<IO::Socket> has been upgraded from version 1.37 to 1.38.
+
+Document the limitations of the isconnected() method.  [perl #123096]
+
+=item *
+
+L<locale> has been upgraded from version 1.04 to 1.05.
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 5.20141020 to 5.20141120.
+
+=item *
+
+L<overload> has been upgraded from version 1.23 to 1.24.
+
+=item *
+
+L<PerlIO::encoding> has been upgraded from version 0.19 to 0.20.
+
+=item *
+
+L<PerlIO::scalar> has been upgraded from version 0.19 to 0.20.
+
+=item *
+
+L<POSIX> has been upgraded from version 1.45 to 1.46.
+
+=item *
+
+L<re> has been upgraded from version 0.27 to 0.28.
+
+=item *
+
+L<Test::Harness> has been upgraded from version 3.33 to 3.34.
+
+=item *
+
+L<Test::Simple> has been upgraded from version 1.001008 to 1.301001_075.
+
+=item *
+
+L<Unicode::UCD> has been upgraded from version 0.58 to 0.59.
+
+=item *
+
+L<warnings> has been upgraded from version 1.28 to 1.29.
+
+=item *
+
+L<XSLoader> has been upgraded from version 0.18 to 0.19.
+
+=back
+
+=head1 Documentation
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perldata/Identifier parsing>
+
+=over 4
+
+=item *
+
+The syntax of single-character variable names has been brought
+up-to-date and more fully explained.
+
+=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 Warnings
+
+=over 4
+
+=item *
+
+L<Use of literal non-graphic characters in variable names is deprecated|perldiag/"Use of literal non-graphic characters in variable names is deprecated">
+
+=item *
+
+A new C<locale> warning category has been created, with the following warning
+messages currently in it:
+
+=over 4
+
+=item *
+
+L<Locale '%s' may not work well.%s|perldiag/Locale '%s' may not work well.%s>
+
+=item *
+
+L<Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".|perldiag/Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".>
+
+=back
+
+=item *
+
+L<Warning: unable to close filehandle %s properly: %s|perldiag/"Warning: unable to close filehandle %s properly: %s">
+
+=item *
+
+The following two warnings for C<tr///> used to be skipped if the
+transliteration contained wide characters, but now they occur regardless of
+whether there are wide characters or not:
+
+L<Useless use of E<sol>d modifier in transliteration operator|perldiag/"Useless use of /d modifier in transliteration operator">
+
+L<Replacement list is longer than search list|perldiag/Replacement list is longer than search list>
+
+=back
+
+=head2 Changes to Existing Diagnostics
+
+=over 4
+
+=item *
+
+L<Quantifier unexpected on zero-length expression in regex mE<sol>%sE<sol>|perldiag/"Quantifier unexpected on zero-length expression in regex m/%s/">.
+
+This message has had the S<"<-- HERE"> marker removed, as it was always
+placed at the end of the regular expression, regardless of where the
+problem actually occurred.  [perl #122680]
+
+=item *
+
+L<Setting $E<sol> to a reference to %s as a form of slurp is deprecated, treating as undef|perldiag/"Setting $/ to a reference to %s as a form of slurp is deprecated, treating as undef">
+
+This warning is now a default warning, like other deprecation warnings.
+
+=back
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item *
+
+F<Configure> with C<-Dmksymlinks> should now be faster. [perl #122002]
+
+=back
+
+=over 4
+
+=item *
+
+As well as the gzip and bzip2 tarballs, this release has been made available as an xz utils compressed tarball.
+
+=back
+
+=head1 Platform Support
+
+=head2 Platform-Specific Notes
+
+=head3 Win32
+
+=over 4
+
+=item *
+
+In the experimental C<:win32> layer, a crash in C<open> was fixed. Also
+opening C</dev/null>, which works the Win32 Perl's normal C<:unix> layer, was
+implemented for C<:win32>.
+L<[perl #122224]|https://rt.perl.org/Ticket/Display.html?id=122224>
+
+=item *
+
+A new makefile option, C<USE_LONG_DOUBLE>, has been added to the Windows
+dmake makefile for gcc builds only.  Set this to "define" if you want perl to
+use long doubles to give more accuracy and range for floating point numbers.
+
+=back
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+C<screaminstr> has been removed. Although marked as public API, it is
+undocumented and has no usage in modern perl versions on CPAN Grep. Calling it
+has been fatal since 5.17.0.
+
+=item *
+
+C<newDEFSVOP>, C<block_start>, C<block_end> and C<intro_my> have been added
+to the API.
+
+=item *
+
+The internal C<convert> function in F<op.c> has been renamed
+C<op_convert_list> and added to the API.
+
+=item *
+
+C<sv_magic> no longer forbids "ext" magic on read-only values.  After all,
+perl can't know whether the custom magic will modify the SV or not.
+[perl #123103]
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+fchmod() and futimes() now set C<$!> when they fail due to being
+passed a closed file handle.  [perl #122703]
+
+=item *
+
+Perl now comes with a corrected Unicode 7.0 for the erratum issued on
+October 21, 2014 (see L<http://www.unicode.org/errata/#current_errata>),
+dealing with glyph shaping in Arabic.
+
+=item *
+
+op_free() no longer crashes due to a stack overflow when freeing a
+deeply recursive op tree. [perl #108276]
+
+=item *
+
+scalarvoid() would crash due to a stack overflow when processing a
+deeply recursive op tree. [perl #108276]
+
+=item *
+
+In Perl 5.20.0, C<$^N> accidentally had the internal UTF8 flag turned off
+if accessed from a code block within a regular expression, effectively
+UTF8-encoding the value.  This has been fixed.  [perl #123135]
+
+=item *
+
+A failed C<semctl> call no longer overwrites existing items on the stack,
+causing C<(semctl(-1,0,0,0))[0]> to give an "uninitialized" warning.
+
+=item *
+
+C<else{foo()}> with no space before C<foo> is now better at assigning the
+right line number to that statement.  [perl #122695]
+
+=item *
+
+Sometimes the assignment in C<@array = split> gets optimised and C<split>
+itself writes directly to the array.  This caused a bug, preventing this
+assignment from being used in lvalue context.  So
+C<(@a=split//,"foo")=bar()> was an error.  (This bug probably goes back to
+Perl 3, when the optimisation was added.)  This optimisation, and the bug,
+started to happen in more cases in 5.21.5.  It has now been fixed.
+[perl #123057]
+
+=item *
+
+When argument lists that fail the checks installed by subroutine
+signatures, the resulting error messages now give the file and line number
+of the caller, not of the called subroutine.  [perl #121374]
+
+=item *
+
+Flip-flop operators (C<..> and C<...> in scalar context) used to maintain
+a separate state for each recursion level (the number of times the
+enclosing sub was called recursively), contrary to the documentation.  Now
+each closure has one internal state for each flip-flop.  [perl #122829]
+
+=item *
+
+C<use>, C<no>, statement labels, special blocks (C<BEGIN>) and pod are now
+permitted as the first thing in a C<map> or C<grep> block, the block after
+C<print> or C<say> (or other functions) returning a handle, and within
+C<${...}>, C<@{...}>, etc.  [perl #122782]
+
+=item *
+
+The repetition operator C<x> now propagates lvalue context to its left-hand
+argument when used in contexts like C<foreach>.  That allows
+C<for(($#that_array)x2) { ... }> to work as expected if the loop modifies
+$_.
+
+=item *
+
+C<(...) x ...> in scalar context used to corrupt the stack if one operand
+were an object with "x" overloading, causing erratic behaviour.
+[perl #121827]
+
+=item *
+
+Assignment to a lexical scalar is often optimised away (as mentioned under
+L</Performance Enhancements>).  Various bugs related to this optimisation
+have been fixed.  Certain operators on the right-hand side would sometimes
+fail to assign the value at all or assign the wrong value, or would call
+STORE twice or not at all on tied variables.  The operators affected were
+C<$foo++>, C<$foo-->, and C<-$foo> under C<use integer>, C<chomp>, C<chr>
+and C<setpgrp>.
+
+=item *
+
+List assignments were sometimes buggy if the same scalar ended up on both
+sides of the assignment due to used of C<tied>, C<values> or C<each>.  The
+result would be the wrong value getting assigned.
+
+=item *
+
+C<setpgrp($nonzero)> (with one argument) was accidentally changed in 5.16
+to mean C<setpgrp(0)>.  This has been fixed.
+
+=item *
+
+C<__SUB__> could return the wrong value or even corrupt memory under the
+debugger (the B<-d> switch) and in subs containing C<eval $string>.
+
+=item *
+
+When C<sub () { $var }> becomes inlinable, it now returns a different
+scalar each time, just as a non-inlinable sub would, though Perl still
+optimises the copy away in cases where it would make no observable
+difference.
+
+=item *
+
+C<my sub f () { $var }> and C<sub () : attr { $var }> are no longer
+eligible for inlining.  The former would crash; the latter would just
+throw the attributes away.  An exception is made for the little-known
+":method" attribute, which does nothing much.
+
+=item *
+
+Inlining of subs with an empty prototype is now more consistent than
+before.  Previously, a sub with multiple statements, all but the last
+optimised away, would be inlinable only if it were an anonymous sub
+containing a string C<eval> or C<state> declaration or closing over an
+outer lexical variable (or any anonymous sub under the debugger).  Now any
+sub that gets folded to a single constant after statements have been
+optimised away is eligible for inlining.  This applies to things like C<sub
+() { jabber() if DEBUG; 42 }>.
+
+Some subroutines with an explicit C<return> were being made inlinable,
+contrary to the documentation,  Now C<return> always prevents inlining.
+
+=item *
+
+On some systems, such as VMS, C<crypt> can return a non-ASCII string.  If a
+scalar assigned to had contained a UTF8 string previously, then C<crypt>
+would not turn off the UTF8 flag, thus corrupting the return value.  This
+would happen with C<$lexical = crypt ...>.
+
+=item *
+
+C<crypt> no longer calls C<FETCH> twice on a tied first argument.
+
+=item *
+
+An unterminated here-doc on the last line of a quote-like operator
+(C<qq[${ <<END }]>, C</(?{ <<END })/>) no longer causes a double free.  It
+started doing so in 5.18.
+
+=item *
+
+Fixed two assertion failures introduced into C<-DPERL_OP_PARENT>
+builds. [perl #108276]
+
+=back
+
+=head1 Known Problems
+
+=over 4
+
+=item *
+
+Starting in 5.21.6, accessing L<perlapi/CvPADLIST> in an XSUB is forbidden.
+CvPADLIST has be reused for a different internal purpose for XSUBs. Guard all
+CvPADLIST expressions with C<CvISXSUB()> if your code doesn't already block
+XSUB CV*s from going through optree CV* expecting code.
+
+=back
+
+=over 4
+
+=item *
+
+Builds on FreeBSD 10.x currently fail when compiling L<POSIX>. A workaround is
+to specify C<-Ui_fenv> when running C<Configure>.
+
+=back
+
+=head1 Errata From Previous Releases
+
+=over 4
+
+=item *
+
+Due to a mistake in the string-copying logic, copying the value of a state
+variable could instead steal the value and undefine the variable.  This
+bug, introduced in 5.20, would happen mostly for long strings (1250 chars
+or more), but could happen for any strings under builds with copy-on-write
+disabled.  [perl #123029]
+
+This bug was actually fixed in 5.21.5, but it was not until after that
+release that this bug, and the fact that it had been fixed, were
+discovered.
+
+=item *
+
+If a named sub tries to access a scalar declared in an outer anonymous sub,
+the variable is not available, so the named sub gets its own undefined
+scalar.  In 5.10, attempts to take a reference to the variable
+(C<\$that_variable>) began returning a reference to a I<copy> of it
+instead.  This was accidentally fixed in 5.21.4, but the bug and its fix
+were not noticed till now.
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.21.6 represents approximately 4 weeks of development since Perl 5.21.5
+and contains approximately 60,000 lines of changes across 920 files from 25
+authors.
+
+Excluding auto-generated files, documentation and release tools, there were
+approximately 48,000 lines of changes to 630 .pm, .t, .c and .h files.
+
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.21.6:
+
+Aaron Crane, Abigail, Andrew Fresh, Andy Dougherty, Brian Fraser, Chad Granum,
+Chris 'BinGOs' Williams, Craig A. Berry, Daniel Dragan, David Mitchell, Doug
+Bell, Father Chrysostomos, Glenn D. Golden, James E Keenan, Jarkko Hietaniemi,
+Jim Cromie, Karen Etheridge, Karl Williamson, Lukas Mai, Ricardo Signes, Shlomi
+Fish, Slaven Rezic, Steve Hay, Tony Cook, Yaroslav Kuzmin.
+
+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 articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+https://rt.perl.org/ .  There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug> program
+included with your release.  Be sure to trim your bug down to a tiny but
+sufficient test case.  Your bug report, along with the output of C<perl -V>,
+will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5-security-report@perl.org.  This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported.  Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+
+=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 72a5a8da28..cb4e09f86d 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -2,297 +2,163 @@
 
 =head1 NAME
 
-perldelta - what is new for perl v5.21.6
+[ 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.21.7
 
 =head1 DESCRIPTION
 
-This document describes differences between the 5.21.5 release and the 5.21.6
+This document describes differences between the 5.21.6 release and the 5.21.7
 release.
 
-If you are upgrading from an earlier release such as 5.21.4, first read
-L<perl5215delta>, which describes differences between 5.21.4 and 5.21.5.
+If you are upgrading from an earlier release such as 5.21.5, first read
+L<perl5216delta>, which describes differences between 5.21.5 and 5.21.6.
 
-=head1 Core Enhancements
+=head1 Notice
 
-=head2 List form of pipe open implemented for Win32
+XXX Any important notices here
 
-The list form of pipe:
+=head1 Core Enhancements
 
-  open my $fh, "-|", "program", @arguments;
+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.
 
-is now implemented on Win32.  It has the same limitations as C<system
-LIST> on Win32, since the Win32 API doesn't accept program arguments
-as a list.
+[ List each enhancement as a =head2 entry ]
 
-=head2 Assignment to list repetition
+=head1 Security
 
-C<(...) x ...> can now be used within a list that is assigned to, as long
-as the left-hand side is a valid lvalue.  This allows C<(undef,undef,$foo)
-= that_function()> to be written as C<((undef)x2, $foo) = that_function()>.
+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.
 
-=head2 C<close> now sets C<$!>
+[ List each security issue as a =head2 entry ]
 
-When an I/O error occurs, the fact that there has been an error is recorded
-in the handle.  C<close> returns false for such a handle.  Previously, the
-value of C<$!> would be untouched by C<close>, so the common convention of
-writing C<close $fh or die $!> did not work reliably.  Now the handle
-records the value of C<$!>, too, and C<close> restores it.
+=head1 Incompatible Changes
 
-=head1 Deprecations
+XXX For a release on a stable branch, this section aspires to be:
 
-=head2 Use of non-graphic characters in single-character variable names
-
-The syntax for single-character variable names is more lenient than
-for longer variable names, allowing the one-character name to be a
-punctuation character or even invisible (a non-graphic).  Perl v5.20
-deprecated the ASCII-range controls as such a name.  Now, all
-non-graphic characters that formerly were allowed are deprecated.
-The practical effect of this occurs only when not under C<S<"use
-utf8">>, and affects just the C1 controls (code points 0x80 through
-0xFF), NO-BREAK SPACE, and SOFT HYPHEN.
-
-=head2 Inlining of C<sub () { $var }> with observable side-effects
-
-In many cases Perl makes sub () { $var } into an inlinable constant
-subroutine, capturing the value of $var at the time the C<sub> expression
-is evaluated.  This can break the closure behaviour in those cases where
-$var is subsequently modified.  The subroutine won't return the new value.
-
-This usage is now deprecated in those cases where the variable could be
-modified elsewhere.  Perl detects those cases and emits a deprecation
-warning.  Such code will likely change in the future and stop producing a
-constant.
-
-If your variable is only modified in the place where it is declared, then
-Perl will continue to make the sub inlinable with no warnings.
-
-    sub make_constant {
-        my $var = shift;
-        return sub () { $var }; # fine
-    }
-
-    sub make_constant_deprecated {
-        my $var;
-        $var = shift;
-        return sub () { $var }; # deprecated
-    }
-
-    sub make_constant_deprecated2 {
-        my $var = shift;
-        log_that_value($var); # could modify $var
-        return sub () { $var }; # deprecated
-    }
-
-In the second example above, detecting that $var is assigned to only once
-is too hard to detect.  That it happens in a spot other than the C<my>
-declaration is enough for Perl to find it suspicious.
-
-This deprecation warning happens only for a simple variable for the body of
-the sub.  (A C<BEGIN> block or C<use> statement inside the sub is ignored,
-because it does not become part of the sub's body.)  For more complex
-cases, such as C<sub () { do_something() if 0; $var }> the behaviour has
-changed such that inlining does not happen if the variable is modifiable
-elsewhere.  Such cases should be rare.
+    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.
 
-=head1 Performance Enhancements
-
-=over 4
+[ List each incompatible change as a =head2 entry ]
 
-=item *
+=head1 Deprecations
 
-C<(...)x1>, C<("constant")x0> and C<($scalar)x0> are now optimised in list
-context.  If the right-hand argument is a constant 1, the repetition
-operator disappears.  If the right-hand argument is a constant 0, the whole
-expressions is optimised to the empty list, so long as the left-hand
-argument is a simple scalar or constant.  C<(foo())x0> is not optimised.
+XXX Any deprecated features, syntax, modules etc. should be listed here.
 
-=item *
+=head2 Module removals
 
-C<substr> assignment is now optimised into 4-argument C<substr> at the end
-of a subroutine (or as the argument to C<return>).  Previously, this
-optimisation only happened in void context.
+XXX Remove this section if inapplicable.
 
-=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.
 
-Assignment to lexical variables is often optimised away.  For instance, in
-C<$lexical = chr $foo>, the C<chr> operator writes directly to the lexical
-variable instead of returning a value that gets copied.  This optimisation
-has been extended to C<split>, C<x> and C<vec> on the right-hand side.  It
-has also been made to work with state variable initialization.
+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 *
+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.
 
-In "\L...", "\Q...", etc., the extra "stringify" op is now optimised away,
-making these just as fast as C<lcfirst>, C<quotemeta>, etc.
+=over
 
-=item *
+=item XXX
 
-Assignment to an empty list is now sometimes faster.  In particular, it
-never calls C<FETCH> on tied arguments on the right-hand side, whereas it
-used to sometimes.
+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
 
-=head1 Modules and Pragmata
-
-=head2 Updated Modules and Pragmata
-
-=over 4
-
-=item *
-
-L<B> has been upgraded from version 1.52 to 1.53.
-
-=item *
-
-L<B::Concise> has been upgraded from version 0.994 to 0.995.
-
-=item *
-
-L<B::Deparse> has been upgraded from version 1.29 to 1.30.
-
-It now deparses C<+sub : attr { ... }> correctly at the start of a
-statement.  Without the initial C<+>, C<sub> would be a statement label.
-
-C<BEGIN> blocks are now emitted in the right place most of the time, but
-the change unfortunately introduced a regression, in that C<BEGIN> blocks
-occurring just before the end of the enclosing block may appear below it
-instead.  So this change may need to be reverted if it cannot be fixed
-before Perl 5.22.  [perl #77452]
-
-B::Deparse no longer puts erroneous C<local> here and there, such as for
-C<LIST = tr/a//d>.  [perl #119815]
-
-Adjacent C<use> statements are no longer accidentally nested if one
-contains a C<do> block.  [perl #115066]
-
-=item *
-
-L<B::Op_private> has been upgraded from version 5.021005 to 5.021006.
-
-It now includes a hash named C<%ops_using>, list all op types that use a
-particular private flag.
-
-=item *
-
-L<CPAN::Meta> has been upgraded from version 2.142690 to 2.143240.
-
-=item *
-
-L<CPAN::Meta::Requirements> has been upgraded from version 2.128 to 2.130.
-
-=item *
-
-L<Devel::Peek> has been upgraded from version 1.18 to 1.19.
-
-=item *
-
-L<Digest::SHA> has been upgraded from version 5.92 to 5.93.
-
-=item *
-
-L<DynaLoader> has been upgraded from version 1.27 to 1.28.
-
-=item *
-
-L<Encode> has been upgraded from version 2.62 to 2.64.
-
-=item *
-
-L<experimental> has been upgraded from version 0.012 to 0.013.
-
-=item *
-
-L<Exporter> has been upgraded from version 5.71 to 5.72.
-
-=item *
-
-L<ExtUtils::MakeMaker> has been upgraded from version 6.98 to 7.02.
-
-=item *
-
-L<ExtUtils::Manifest> has been upgraded from version 1.68 to 1.69.
+[ List each other deprecation as a =head2 entry ]
 
-=item *
+=head1 Performance Enhancements
 
-L<ExtUtils::ParseXS> has been upgraded from version 3.25 to 3.26.
+XXX Changes which enhance performance without changing behaviour go here.
+There may well be none in a stable release.
 
-=item *
+[ List each enhancement as a =item entry ]
 
-L<HTTP::Tiny> has been upgraded from version 0.050 to 0.051.
+=over 4
 
 =item *
 
-L<I18N::Langinfo> has been upgraded from version 0.11 to 0.12.
+XXX
 
-=item *
-
-L<IO::Socket> has been upgraded from version 1.37 to 1.38.
+=back
 
-Document the limitations of the isconnected() method.  [perl #123096]
+=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.
 
-L<locale> has been upgraded from version 1.04 to 1.05.
+[ Within each section, list entries as a =item entry ]
 
-=item *
+=head2 New Modules and Pragmata
 
-L<Module::CoreList> has been upgraded from version 5.20141020 to 5.20141120.
+=over 4
 
 =item *
 
-L<overload> has been upgraded from version 1.23 to 1.24.
-
-=item *
+XXX
 
-L<PerlIO::encoding> has been upgraded from version 0.19 to 0.20.
+=back
 
-=item *
+=head2 Updated Modules and Pragmata
 
-L<PerlIO::scalar> has been upgraded from version 0.19 to 0.20.
+=over 4
 
 =item *
 
-L<POSIX> has been upgraded from version 1.45 to 1.46.
+L<XXX> has been upgraded from version A.xx to B.yy.
 
-=item *
+=back
 
-L<re> has been upgraded from version 0.27 to 0.28.
+=head2 Removed Modules and Pragmata
 
-=item *
-
-L<Test::Harness> has been upgraded from version 3.33 to 3.34.
+=over 4
 
 =item *
 
-L<Test::Simple> has been upgraded from version 1.001008 to 1.301001_075.
-
-=item *
+XXX
 
-L<Unicode::UCD> has been upgraded from version 0.58 to 0.59.
+=back
 
-=item *
+=head1 Documentation
 
-L<warnings> has been upgraded from version 1.28 to 1.29.
+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>.
 
-=item *
+=head2 New Documentation
 
-L<XSLoader> has been upgraded from version 0.18 to 0.19.
+XXX Changes which create B<new> files in F<pod/> go here.
 
-=back
+=head3 L<XXX>
 
-=head1 Documentation
+XXX Description of the purpose of the new file here
 
 =head2 Changes to Existing Documentation
 
-=head3 L<perldata/Identifier parsing>
+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.
+
+=head3 L<XXX>
 
 =over 4
 
 =item *
 
-The syntax of single-character variable names has been brought
-up-to-date and more fully explained.
+XXX Description of the change here
 
 =back
 
@@ -302,319 +168,193 @@ 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
+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.
 
-=head3 New Warnings
-
-=over 4
-
-=item *
-
-L<Use of literal non-graphic characters in variable names is deprecated|perldiag/"Use of literal non-graphic characters in variable names is deprecated">
+=head2 New Diagnostics
 
-=item *
+XXX Newly added diagnostic messages go under here, separated into New Errors
+and New Warnings
 
-A new C<locale> warning category has been created, with the following warning
-messages currently in it:
+=head3 New Errors
 
 =over 4
 
 =item *
 
-L<Locale '%s' may not work well.%s|perldiag/Locale '%s' may not work well.%s>
-
-=item *
-
-L<Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".|perldiag/Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".>
+XXX L<message|perldiag/"message">
 
 =back
 
-=item *
+=head3 New Warnings
 
-L<Warning: unable to close filehandle %s properly: %s|perldiag/"Warning: unable to close filehandle %s properly: %s">
+=over 4
 
 =item *
 
-The following two warnings for C<tr///> used to be skipped if the
-transliteration contained wide characters, but now they occur regardless of
-whether there are wide characters or not:
-
-L<Useless use of E<sol>d modifier in transliteration operator|perldiag/"Useless use of /d modifier in transliteration operator">
-
-L<Replacement list is longer than search list|perldiag/Replacement list is longer than search list>
+XXX L<message|perldiag/"message">
 
 =back
 
 =head2 Changes to Existing Diagnostics
 
-=over 4
-
-=item *
-
-L<Quantifier unexpected on zero-length expression in regex mE<sol>%sE<sol>|perldiag/"Quantifier unexpected on zero-length expression in regex m/%s/">.
+XXX Changes (i.e. rewording) of diagnostic messages go here
 
-This message has had the S<"<-- HERE"> marker removed, as it was always
-placed at the end of the regular expression, regardless of where the
-problem actually occurred.  [perl #122680]
+=over 4
 
 =item *
 
-L<Setting $E<sol> to a reference to %s as a form of slurp is deprecated, treating as undef|perldiag/"Setting $/ to a reference to %s as a form of slurp is deprecated, treating as undef">
-
-This warning is now a default warning, like other deprecation warnings.
+XXX Describe change here
 
 =back
 
-=head1 Configuration and Compilation
+=head1 Utility Changes
 
-=over 4
+XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
+Most of these are built within the directory F<utils>.
 
-=item *
-
-F<Configure> with C<-Dmksymlinks> should now be faster. [perl #122002]
+[ 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. ]
 
-=back
+=head2 L<XXX>
 
 =over 4
 
 =item *
 
-As well as the gzip and bzip2 tarballs, this release has been made available as an xz utils compressed tarball.
+XXX
 
 =back
 
-=head1 Platform Support
+=head1 Configuration and Compilation
 
-=head2 Platform-Specific Notes
+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.
 
-=head3 Win32
+[ List changes as a =item entry ].
 
 =over 4
 
 =item *
 
-In the experimental C<:win32> layer, a crash in C<open> was fixed. Also
-opening C</dev/null>, which works the Win32 Perl's normal C<:unix> layer, was
-implemented for C<:win32>.
-L<[perl #122224]|https://rt.perl.org/Ticket/Display.html?id=122224>
-
-=item *
-
-A new makefile option, C<USE_LONG_DOUBLE>, has been added to the Windows
-dmake makefile for gcc builds only.  Set this to "define" if you want perl to
-use long doubles to give more accuracy and range for floating point numbers.
+XXX
 
 =back
 
-=head1 Internal Changes
-
-=over 4
-
-=item *
-
-C<screaminstr> has been removed. Although marked as public API, it is
-undocumented and has no usage in modern perl versions on CPAN Grep. Calling it
-has been fatal since 5.17.0.
-
-=item *
-
-C<newDEFSVOP>, C<block_start>, C<block_end> and C<intro_my> have been added
-to the API.
-
-=item *
-
-The internal C<convert> function in F<op.c> has been renamed
-C<op_convert_list> and added to the API.
-
-=item *
-
-C<sv_magic> no longer forbids "ext" magic on read-only values.  After all,
-perl can't know whether the custom magic will modify the SV or not.
-[perl #123103]
+=head1 Testing
 
-=back
+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.
 
-=head1 Selected Bug Fixes
+[ List each test improvement as a =item entry ]
 
 =over 4
 
 =item *
 
-fchmod() and futimes() now set C<$!> when they fail due to being
-passed a closed file handle.  [perl #122703]
-
-=item *
-
-Perl now comes with a corrected Unicode 7.0 for the erratum issued on
-October 21, 2014 (see L<http://www.unicode.org/errata/#current_errata>),
-dealing with glyph shaping in Arabic.
-
-=item *
-
-op_free() no longer crashes due to a stack overflow when freeing a
-deeply recursive op tree. [perl #108276]
-
-=item *
-
-scalarvoid() would crash due to a stack overflow when processing a
-deeply recursive op tree. [perl #108276]
+XXX
 
-=item *
-
-In Perl 5.20.0, C<$^N> accidentally had the internal UTF8 flag turned off
-if accessed from a code block within a regular expression, effectively
-UTF8-encoding the value.  This has been fixed.  [perl #123135]
-
-=item *
-
-A failed C<semctl> call no longer overwrites existing items on the stack,
-causing C<(semctl(-1,0,0,0))[0]> to give an "uninitialized" warning.
-
-=item *
+=back
 
-C<else{foo()}> with no space before C<foo> is now better at assigning the
-right line number to that statement.  [perl #122695]
+=head1 Platform Support
 
-=item *
+XXX Any changes to platform support should be listed in the sections below.
 
-Sometimes the assignment in C<@array = split> gets optimised and C<split>
-itself writes directly to the array.  This caused a bug, preventing this
-assignment from being used in lvalue context.  So
-C<(@a=split//,"foo")=bar()> was an error.  (This bug probably goes back to
-Perl 3, when the optimisation was added.)  This optimisation, and the bug,
-started to happen in more cases in 5.21.5.  It has now been fixed.
-[perl #123057]
+[ Within the sections, list each platform as a =item entry with specific
+changes as paragraphs below it. ]
 
-=item *
+=head2 New Platforms
 
-When argument lists that fail the checks installed by subroutine
-signatures, the resulting error messages now give the file and line number
-of the caller, not of the called subroutine.  [perl #121374]
+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.
 
-=item *
+=over 4
 
-Flip-flop operators (C<..> and C<...> in scalar context) used to maintain
-a separate state for each recursion level (the number of times the
-enclosing sub was called recursively), contrary to the documentation.  Now
-each closure has one internal state for each flip-flop.  [perl #122829]
+=item XXX-some-platform
 
-=item *
+XXX
 
-C<use>, C<no>, statement labels, special blocks (C<BEGIN>) and pod are now
-permitted as the first thing in a C<map> or C<grep> block, the block after
-C<print> or C<say> (or other functions) returning a handle, and within
-C<${...}>, C<@{...}>, etc.  [perl #122782]
+=back
 
-=item *
+=head2 Discontinued Platforms
 
-The repetition operator C<x> now propagates lvalue context to its left-hand
-argument when used in contexts like C<foreach>.  That allows
-C<for(($#that_array)x2) { ... }> to work as expected if the loop modifies
-$_.
+XXX List any platforms that this version of perl no longer compiles on.
 
-=item *
+=over 4
 
-C<(...) x ...> in scalar context used to corrupt the stack if one operand
-were an object with "x" overloading, causing erratic behaviour.
-[perl #121827]
+=item XXX-some-platform
 
-=item *
+XXX
 
-Assignment to a lexical scalar is often optimised away (as mentioned under
-L</Performance Enhancements>).  Various bugs related to this optimisation
-have been fixed.  Certain operators on the right-hand side would sometimes
-fail to assign the value at all or assign the wrong value, or would call
-STORE twice or not at all on tied variables.  The operators affected were
-C<$foo++>, C<$foo-->, and C<-$foo> under C<use integer>, C<chomp>, C<chr>
-and C<setpgrp>.
+=back
 
-=item *
+=head2 Platform-Specific Notes
 
-List assignments were sometimes buggy if the same scalar ended up on both
-sides of the assignment due to used of C<tied>, C<values> or C<each>.  The
-result would be the wrong value getting assigned.
+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.
 
-=item *
+=over 4
 
-C<setpgrp($nonzero)> (with one argument) was accidentally changed in 5.16
-to mean C<setpgrp(0)>.  This has been fixed.
+=item XXX-some-platform
 
-=item *
+XXX
 
-C<__SUB__> could return the wrong value or even corrupt memory under the
-debugger (the B<-d> switch) and in subs containing C<eval $string>.
+=back
 
-=item *
+=head1 Internal Changes
 
-When C<sub () { $var }> becomes inlinable, it now returns a different
-scalar each time, just as a non-inlinable sub would, though Perl still
-optimises the copy away in cases where it would make no observable
-difference.
+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 *
+[ List each change as a =item entry ]
 
-C<my sub f () { $var }> and C<sub () : attr { $var }> are no longer
-eligible for inlining.  The former would crash; the latter would just
-throw the attributes away.  An exception is made for the little-known
-":method" attribute, which does nothing much.
+=over 4
 
 =item *
 
-Inlining of subs with an empty prototype is now more consistent than
-before.  Previously, a sub with multiple statements, all but the last
-optimised away, would be inlinable only if it were an anonymous sub
-containing a string C<eval> or C<state> declaration or closing over an
-outer lexical variable (or any anonymous sub under the debugger).  Now any
-sub that gets folded to a single constant after statements have been
-optimised away is eligible for inlining.  This applies to things like C<sub
-() { jabber() if DEBUG; 42 }>.
-
-Some subroutines with an explicit C<return> were being made inlinable,
-contrary to the documentation,  Now C<return> always prevents inlining.
-
-=item *
+XXX
 
-On some systems, such as VMS, C<crypt> can return a non-ASCII string.  If a
-scalar assigned to had contained a UTF8 string previously, then C<crypt>
-would not turn off the UTF8 flag, thus corrupting the return value.  This
-would happen with C<$lexical = crypt ...>.
+=back
 
-=item *
+=head1 Selected Bug Fixes
 
-C<crypt> no longer calls C<FETCH> twice on a tied first argument.
+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>.
 
-=item *
+[ List each fix as a =item entry ]
 
-An unterminated here-doc on the last line of a quote-like operator
-(C<qq[${ <<END }]>, C</(?{ <<END })/>) no longer causes a double free.  It
-started doing so in 5.18.
+=over 4
 
 =item *
 
-Fixed two assertion failures introduced into C<-DPERL_OP_PARENT>
-builds. [perl #108276]
+XXX
 
 =back
 
 =head1 Known Problems
 
-=over 4
-
-=item *
-
-Starting in 5.21.6, accessing L<perlapi/CvPADLIST> in an XSUB is forbidden.
-CvPADLIST has be reused for a different internal purpose for XSUBs. Guard all
-CvPADLIST expressions with C<CvISXSUB()> if your code doesn't already block
-XSUB CV*s from going through optree CV* expecting code.
+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.
 
-=back
+[ List each fix as a =item entry ]
 
 =over 4
 
 =item *
 
-Builds on FreeBSD 10.x currently fail when compiling L<POSIX>. A workaround is
-to specify C<-Ui_fenv> when running C<Configure>.
+XXX
 
 =back
 
@@ -624,57 +364,21 @@ to specify C<-Ui_fenv> when running C<Configure>.
 
 =item *
 
-Due to a mistake in the string-copying logic, copying the value of a state
-variable could instead steal the value and undefine the variable.  This
-bug, introduced in 5.20, would happen mostly for long strings (1250 chars
-or more), but could happen for any strings under builds with copy-on-write
-disabled.  [perl #123029]
-
-This bug was actually fixed in 5.21.5, but it was not until after that
-release that this bug, and the fact that it had been fixed, were
-discovered.
-
-=item *
-
-If a named sub tries to access a scalar declared in an outer anonymous sub,
-the variable is not available, so the named sub gets its own undefined
-scalar.  In 5.10, attempts to take a reference to the variable
-(C<\$that_variable>) began returning a reference to a I<copy> of it
-instead.  This was accidentally fixed in 5.21.4, but the bug and its fix
-were not noticed till now.
+XXX Add anything here that we forgot to add, or were mistaken about, in
+the perldelta of a previous release.
 
 =back
 
-=head1 Acknowledgements
-
-Perl 5.21.6 represents approximately 4 weeks of development since Perl 5.21.5
-and contains approximately 60,000 lines of changes across 920 files from 25
-authors.
+=head1 Obituary
 
-Excluding auto-generated files, documentation and release tools, there were
-approximately 48,000 lines of changes to 630 .pm, .t, .c and .h files.
+XXX If any significant core contributor has died, we've added a short obituary
+here.
 
-Perl continues to flourish into its third decade thanks to a vibrant community
-of users and developers. The following people are known to have contributed the
-improvements that became Perl 5.21.6:
-
-Aaron Crane, Abigail, Andrew Fresh, Andy Dougherty, Brian Fraser, Chad Granum,
-Chris 'BinGOs' Williams, Craig A. Berry, Daniel Dragan, David Mitchell, Doug
-Bell, Father Chrysostomos, Glenn D. Golden, James E Keenan, Jarkko Hietaniemi,
-Jim Cromie, Karen Etheridge, Karl Williamson, Lukas Mai, Ricardo Signes, Shlomi
-Fish, Slaven Rezic, Steve Hay, Tony Cook, Yaroslav Kuzmin.
-
-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.
+=head1 Acknowledgements
 
-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.
+XXX Generate this with:
 
-For a more complete list of all of Perl's historical contributors, please see
-the F<AUTHORS> file in the Perl source distribution.
+  perl Porting/acknowledgements.pl v5.21.6..HEAD
 
 =head1 Reporting Bugs
 
diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template
index 90336202aa..d8b76507f6 100644
--- a/vms/descrip_mms.template
+++ b/vms/descrip_mms.template
@@ -307,7 +307,7 @@ utils : $(utils1) $(utils2) $(utils3) $(utils4) $(utils5)
 extra.pods : miniperl
 	@ @extra_pods.com
 
-PERLDELTA_CURRENT = [.pod]perl5216delta.pod
+PERLDELTA_CURRENT = [.pod]perl5217delta.pod
 
 $(PERLDELTA_CURRENT) : [.pod]perldelta.pod
 	Copy/NoConfirm/Log $(MMS$SOURCE) $(PERLDELTA_CURRENT)
diff --git a/win32/Makefile b/win32/Makefile
index e5c3c86183..bdcd2876c1 100644
--- a/win32/Makefile
+++ b/win32/Makefile
@@ -1162,7 +1162,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\perl5216delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5217delta.pod
 	cd ..\win32
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(MINIPERL) -I..\lib ..\autodoc.pl ..
@@ -1258,7 +1258,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 \
-	    perl5216delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+	    perl5217delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
 	    perlapi.pod perlbs2000.pod perlce.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 17caf4ebbb..cb6c3b1c2d 100644
--- a/win32/makefile.mk
+++ b/win32/makefile.mk
@@ -1432,7 +1432,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\perl5216delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5217delta.pod
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(MINIPERL) -I..\lib ..\autodoc.pl ..
 	$(MINIPERL) -I..\lib ..\pod\perlmodlib.PL -q ..
@@ -1527,7 +1527,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 \
-	    perl5216delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+	    perl5217delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
 	    perlapi.pod perlbs2000.pod perlce.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 a26826b987..e10aa453e1 100644
--- a/win32/pod.mak
+++ b/win32/pod.mak
@@ -44,6 +44,7 @@ POD = perl.pod	\
 	perl5214delta.pod	\
 	perl5215delta.pod	\
 	perl5216delta.pod	\
+	perl5217delta.pod	\
 	perl561delta.pod	\
 	perl56delta.pod	\
 	perl581delta.pod	\
@@ -181,6 +182,7 @@ MAN = perl.man	\
 	perl5214delta.man	\
 	perl5215delta.man	\
 	perl5216delta.man	\
+	perl5217delta.man	\
 	perl561delta.man	\
 	perl56delta.man	\
 	perl581delta.man	\
@@ -318,6 +320,7 @@ HTML = perl.html	\
 	perl5214delta.html	\
 	perl5215delta.html	\
 	perl5216delta.html	\
+	perl5217delta.html	\
 	perl561delta.html	\
 	perl56delta.html	\
 	perl581delta.html	\
@@ -455,6 +458,7 @@ TEX = perl.tex	\
 	perl5214delta.tex	\
 	perl5215delta.tex	\
 	perl5216delta.tex	\
+	perl5217delta.tex	\
 	perl561delta.tex	\
 	perl56delta.tex	\
 	perl581delta.tex	\