Create a perldelta for 5.15.5

11 files changed, 767 insertions, 365 deletions

diff --git a/MANIFEST b/MANIFEST
index db8ef48e2c..e5a0da169d 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4478,6 +4478,7 @@ pod/perl5150delta.pod		Perl changes in version 5.15.0
 pod/perl5151delta.pod		Perl changes in version 5.15.1
 pod/perl5152delta.pod		Perl changes in version 5.15.2
 pod/perl5153delta.pod		Perl changes in version 5.15.3
+pod/perl5154delta.pod		Perl changes in version 5.15.4
 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 407c3b353e..22358882c6 100755
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -478,7 +478,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/perl5154delta.pod pod/perlapi.pod pod/perlintern.pod pod/perlmodlib.pod pod/perluniprops.pod
+perltoc_pod_prereqs = extra.pods pod/perl5155delta.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
 
@@ -1054,8 +1054,8 @@ pod/perlintern.pod: $(MINIPERL_EXE) autodoc.pl embed.fnc
 pod/perlmodlib.pod: $(MINIPERL_EXE) pod/perlmodlib.PL MANIFEST
 	$(MINIPERL) $(Icwd) pod/perlmodlib.PL -q
 
-pod/perl5154delta.pod: pod/perldelta.pod
-	$(LNS) perldelta.pod pod/perl5154delta.pod
+pod/perl5155delta.pod: pod/perldelta.pod
+	$(LNS) perldelta.pod pod/perl5155delta.pod
 
 extra.pods: $(MINIPERL_EXE)
 	-@test ! -f extra.pods || rm -f `cat extra.pods`
diff --git a/pod.lst b/pod.lst
index 1e60c7901c..6b69140891 100644
--- a/pod.lst
+++ b/pod.lst
@@ -136,6 +136,7 @@ h Miscellaneous
 
   perlhist		Perl history records
   perldelta		Perl changes since previous version
+  perl5155delta		Perl changes in version 5.15.5
   perl5154delta		Perl changes in version 5.15.4
   perl5153delta		Perl changes in version 5.15.3
   perl5152delta		Perl changes in version 5.15.2
diff --git a/pod/.gitignore b/pod/.gitignore
index a207aeb08b..394aa805ea 100644
--- a/pod/.gitignore
+++ b/pod/.gitignore
@@ -58,7 +58,7 @@
 /podselect.bat
 
 # generated
-/perl5154delta.pod
+/perl5155delta.pod
 /perlapi.pod
 /perlintern.pod
 *.html
diff --git a/pod/perl.pod b/pod/perl.pod
index 4f5cd6285d..d41240411c 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -159,6 +159,7 @@ For ease of access, the Perl manual has been split up into several sections.
 
     perlhist		Perl history records
     perldelta		Perl changes since previous version
+    perl5154delta	Perl changes in version 5.15.4
     perl5153delta	Perl changes in version 5.15.3
     perl5152delta	Perl changes in version 5.15.2
     perl5151delta	Perl changes in version 5.15.1
diff --git a/pod/perl5154delta.pod b/pod/perl5154delta.pod
new file mode 100644
index 0000000000..b8631e22e2
--- /dev/null
+++ b/pod/perl5154delta.pod
@@ -0,0 +1,579 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5154delta - what is new for perl v5.15.4
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.15.3 release and
+the 5.15.4 release.
+
+If you are upgrading from an earlier release such as 5.15.3, first read
+L<perl5153delta>, which describes differences between 5.15.3 and
+5.15.4.
+
+=head1 Core Enhancements
+
+=head2 $^X converted to an absolute path on FreeBSD, OS X and Solaris
+
+C<$^X> is now converted to an absolute path on OS X, FreeBSD (without
+needing F</proc> mounted) and Solaris 10 and 11. This augments the
+previous approach of using F</proc> on Linux, FreeBSD and NetBSD
+(in all cases, where mounted).
+
+This makes relocatable perl installations more useful on these platforms.
+(See "Relocatable @INC" in F<INSTALL>)
+
+=head2 Unicode Symbol Names
+
+Perl now has proper support for Unicode in symbol names.  It used to be
+that C<*{$foo}> would ignore the internal UTF8 flag and use the bytes of
+the underlying representation to look up the symbol.  That meant that
+C<*{"\x{100}"}> and C<*{"\xc4\x80"}> would return the same thing.  All
+these parts of Perl have been fixed to account for Unicode:
+
+=over
+
+=item *
+
+Method names (including those passed to C<use overload>)
+
+=item *
+
+Typeglob names (including names of variables, subroutines and filehandles)
+
+=item *
+
+Package names
+
+=item *
+
+Constant subroutine names (not null-clean yet)
+
+=item *
+
+C<goto>
+
+=item *
+
+Symbolic dereferencing
+
+=item *
+
+Second argument to C<bless()> and C<tie()>
+
+=item *
+
+Return value of C<ref()>
+
+=item *
+
+Package names returned by C<caller()>
+
+=item *
+
+Subroutine prototypes
+
+=item *
+
+Attributes
+
+=item *
+
+Various warnings and error messages that mention variable names or values,
+methods, etc.
+
+=back
+
+In addition, a parsing bug has been fixed that prevented C<*{é}> from
+implicitly quoting the name, but instead interpreted it as C<*{+é}>, which
+would cause a strict violation.
+
+C<*{"*a::b"}> automatically strips off the * if it is followed by an ASCII
+letter.  That has been extended to all Unicode identifier characters.
+
+C<$é> is now subject to "Used only once" warnings.  It used to be exempt,
+as it was treated as a punctuation variable.
+
+Also, single-character Unicode punctuation variables (like $‰) are now
+supported [perl #69032].  They are also supported with C<our> and C<my>,
+but that is a mistake that will be fixed before 5.16.
+
+=head2 Support for Embedded Nulls
+
+Some parts of Perl did not work correctly with nulls (C<chr 0>) embedded in
+strings.  That meant that, for instance, C<< $m = "a\0b"; foo->$m >> would
+call the "a" method, instead of the actual method name contained in $m.
+These parts of perl have been fixed to support nulls:
+
+=over
+
+=item *
+
+Method names
+
+=item *
+
+Typeglob names (including filehandle names)
+
+=item *
+
+Package names
+
+=item *
+
+Autoloading
+
+=item *
+
+Return value of C<ref()>
+
+=item *
+
+Package names returned by C<caller()>
+
+=item *
+
+Filehandle warnings
+
+=item *
+
+Typeglob elements (C<*foo{"THING\0stuff"}>)
+
+=item *
+
+Signal names
+
+=item *
+
+Various warnings and error messages that mention variable names or values,
+methods, etc.
+
+=back
+
+One side effect of these changes is that blessing into "\0" no longer
+causes C<ref()> to return false.
+
+=head2 Autoloaded sort Subroutines
+
+Custom sort subroutines can now be autoloaded [perl #30661]:
+
+    sub AUTOLOAD { ... }
+    @sorted = sort foo @list; # uses AUTOLOAD
+
+=head2 Improved typemaps for Some Builtin Types
+
+Most XS authors will be aware that there is a longstanding bug
+in the OUTPUT typemap for T_AVREF (C<AV*>), T_HVREF (C<HV*>),
+T_CVREF (C<CV*>), and T_SVREF (C<SVREF> or C<\$foo>) that requires
+manually decrementing the reference count of the return value
+instead of the typemap taking care of this. For
+backwards-compatibility, this cannot be changed in the default
+typemaps. But we now provide additional typemaps
+C<T_AVREF_REFCOUNT_FIXED>, etc. that do not exhibit this bug.
+Using them in your extension is as simple as having one line
+in your C<TYPEMAP> section:
+
+  HV*	T_HVREF_REFCOUNT_FIXED
+
+=head1 Performance Enhancements
+
+=over 4
+
+=item *
+
+C<substr> no longer calculates a value to return when called in void
+context.
+
+=back
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Archive::Tar> has been upgraded from version 1.78 to version 1.80.
+
+=item *
+
+L<base> has been upgraded from version 2.17 to version 2.18.
+
+C<base> no longer sets a module's C<$VERSION> to "-1" when a module it loads
+does not define a C<$VERSION>.  This change has been made because "-1" is not
+a valid version number under the new "lax" criteria used internally by
+C<UNIVERSAL::VERSION>.  (See L<version> for more on "lax" version criteria.)
+
+C<base> no longer internally skips loading modules it has already loaded and
+instead relies on C<require> to inspect C<%INC>.  This fixes a bug when C<base>
+is used with code that clear C<%INC> to force a module to be reloaded.
+
+=item *
+
+L<Digest> has been upgraded from version 1.16 to version 1.17.
+
+=item *
+
+L<DynaLoader> has been upgraded from version 1.13 to 1.14.
+
+It stopped exporting its symbols with the ExtUtils::ParseXS changes in
+5.15.2.  Now it exports them once more.
+
+=item *
+
+L<ExtUtils::MakeMaker> has been upgraded from version 6.59 to version 6.61_01.
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded from version 3.04_04 to version 3.05.
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.56 to 2.57.
+
+=item *
+
+L<Module::Load> has been upgraded from version 0.20 to version 0.22.
+
+Resolve possible security problem [http://goo.gl/YzHRU] where a '::' prefixed
+module can 'jump' out of @INC
+
+=item *
+
+L<perlfaq> has been upgraded from version 5.0150034 to version 5.0150035.
+
+=item *
+
+L<Unicode::Collate> has been upgraded from version 0.78 to version 0.80.
+
+Locales updated to CLDR 2.0: ar, be, bg, ha, hr, kk, lt.
+Newly supported locales: as, fi__phonebook, gu, hi, kn, kok and ln.
+
+=back
+
+=head1 Documentation
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perlfunc>, L<open>
+
+=over 4
+
+=item *
+
+As an accident of history, C<open $fh, "<:", ...> applies the default
+layers for the platform (C<:raw> on Unix, C<:crlf> on Windows), ignoring
+whatever is declared by L<open.pm|open>.  This seems such a useful feature
+it has been documented in L<perlfunc|perlfunc/open> and L<open>.
+
+=back
+
+=head3 L<perlapi>
+
+=over 4
+
+=item *
+
+The HV API has long accepted negative lengths to indicate that the key is
+in UTF8.  Now this is documented.
+
+=item *
+
+The C<boolSV()> macro is now documented.
+
+=back
+
+=head3 L<perlguts>
+
+=over 4
+
+=item *
+
+A new section, L<Autoloading with XSUBs|perlguts/Autoloading with XSUBs>,
+has been added, which explains the two APIs for accessing the name of the
+autoloaded sub.
+
+=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 Changes to Existing Diagnostics
+
+=over 4
+
+=item *
+
+The message,
+"Code point 0x%X is not Unicode, no properties match it; all inverse
+prop erties do" has been changed to "Code point 0x%X is not Unicode, all
+\p{} matches fail; all \P{} matches succeed"
+
+=back
+
+=head1 Testing
+
+=over 4
+
+=item *
+
+F<t/porting/checkcfgvar.t> now tests that all config.sh-style files are
+complete. These are used by the various non-*nix to generate their
+F<config.h>, and an incomplete input file will generate invalid output.
+
+=back
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+These new functions have been added as part of the work on Unicode symbols:
+
+    HvNAMELEN
+    HvNAMEUTF8
+    HvENAMELEN
+    HvENAMEUTF8
+    gv_init_pv
+    gv_init_pvn
+    gv_init_pvsv
+    gv_fetchmeth_pv
+    gv_fetchmeth_pvn
+    gv_fetchmeth_sv
+    gv_fetchmeth_pv_autoload
+    gv_fetchmeth_pvn_autoload
+    gv_fetchmeth_sv_autoload
+    gv_fetchmethod_pv_flags
+    gv_fetchmethod_pvn_flags
+    gv_fetchmethod_sv_flags
+    gv_autoload_pv
+    gv_autoload_pvn
+    gv_autoload_sv
+    newGVgen_flags
+    sv_derived_from_pv
+    sv_derived_from_pvn
+    sv_derived_from_sv
+    sv_does_pv
+    sv_does_pvn
+    sv_does_sv
+    whichsig_pv
+    whichsig_pvn
+    whichsig_sv
+
+The gv_fetchmethod_*_flags functions, like gv_fetchmethod_flags, are
+experimental and may change in a future release.
+
+=item *
+
+The following functions were added.  These are I<not> part of the API:
+
+    GvNAMEUTF8
+    GvENAMELEN
+    GvENAME_HEK
+    CopSTASH_flags
+    CopSTASH_flags_set
+    PmopSTASH_flags
+    PmopSTASH_flags_set
+    sv_sethek
+    HEKfARG
+
+There is also a C<HEKf> macro corresponding to C<SVf>, for
+interpolating HEKs in formatted strings.
+
+=item *
+
+C<sv_catpvn_flags> takes a couple of new internal-only flags,
+C<SV_CATBYTES> and C<SV_CATUTF8>, which tell it whether the char array to
+be concatenated is UTF8.  This allows for more efficient concatenation than
+creating temporary SVs to pass to C<sv_catsv>.
+
+=item *
+
+For XS AUTOLOAD subs, $AUTOLOAD is set once more, as it was in 5.6.0.  This
+is in addition to setting C<SvPVX(cv)>, for compatibility with 5.8 to 5.14.
+See L<perlguts/Autoloading with XSUBs>.
+
+=item *
+
+Perl now checks whether the array (the linearised isa) returned by a MRO
+plugin begins with the name of the class itself, for which the array was
+created, instead of assuming that it does.  This prevents the first element
+from being skipped during method lookup.  It also means that
+C<mro::get_linear_isa> may return an array with one more element than the
+MRO plugin provided [perl #94306].
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+In Perl 5.14.0, C<$tainted ~~ @array> stopped working properly.  Sometimes
+it would erroneously fail (when C<$tainted> contained a string that occurs
+in the array I<after> the first element) or erroneously succeed (when
+C<undef> occurred after the first element) [perl #93590].
+
+=item *
+
+Perl 5.15.0 introduced a minor regression, in that an object referenced by
+a deleted hash element would be able to access the freed element from its
+DESTROY method, causing panic errors [perl #99660].
+
+=item *
+
+Functions in the CORE package can now be called as methods.  That used to
+work only when they had been called or referenced already.  So
+C<< "foo"->CORE::ucfirst >> returns Foo.
+
+=item *
+
+C<use> and C<require> are no longer affected by the I/O layers active in
+the caller's scope (enabled by L<open.pm|open>) [perl #96008].
+
+=item *
+
+Errors that occur when methods cannot be found during overloading now
+mention the correct package name, as they did in 5.8.x, instead of
+erroneously mentioning the "overload" package, as they have since 5.10.0.
+
+=item *
+
+Undefining C<%overload::> no longer causes a crash.
+
+=item *
+
+C<our $::é; $é> (which is invalid) no longer produces the "Compilation
+error at lib/utf8_heavy.pl..." error message, which it started emitting in
+5.10.0 [perl #99984].
+
+=item *
+
+A minor regression, introduced Perl 5.15.0, has been fixed in which some
+regular expression Unicode property matches (C<\p{...}>) matched
+non-Unicode code points.
+
+=item *
+
+In case-insensitive regular expression pattern matching, no longer on
+UTF-8 encoded strings does the scan for the start of match only look at
+the first possible position.  This caused matches such as
+C<"f\x{FB00}" =~ /ff/i> to fail.
+
+=item *
+
+On 64-bit systems, C<read()> now understands large string offsets beyond
+the 32-bit range.
+
+=item *
+
+Errors that occur when processing subroutine attributes no longer cause the
+subroutine's op tree to leak.
+
+=item *
+
+C<sort> now works once more with custom sort routines that are XSUBs.  It
+stopped working in 5.10.0.
+
+=item *
+
+C<sort> with a constant for a custom sort routine, although it produces
+unsorted results, no longer crashes.  It started crashing in 5.10.0.
+
+=item *
+
+Warnings produced when a custom sort routine returns a non-numeric value
+now contain "in sort"; e.g., "Use of uninitialized value in sort".
+
+=item *
+
+C<< sort { $a <=> $b } >>, which is optimised internally, now produces
+"uninitialized" warnings for NaNs (not-a-number values), since C<< <=> >>
+returns C<undef> for those.  This brings it in line with
+S<C<< sort { 1; $a <=> $b } >>> and other more complex cases, which are not
+optimised [perl #94390].
+
+=item *
+
+C<..> and C<...> in list context now call FETCH only once on tied
+arguments, instead of three or four times [perl #53554].
+
+=item *
+
+C<..> and C<...> in list context now mention the name of the variable in
+"uninitialized" warnings for string (as opposed to numeric) ranges.
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.15.4 represents approximately 1 month of development since Perl 5.15.3
+and contains approximately 31,000 lines of changes across 350 files from 23
+authors.
+
+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.15.4:
+
+Alan Haggai Alavi, Brian Fraser, Chip Salzenberg, Chris 'BinGOs' Williams, Dave
+Rolsky, David Golden, David Mitchell, Dennis Kaarsemaker, Eric Brine, Father
+Chrysostomos, Florian Ragwitz, George Greer, Gerard Goossen, H.Merijn Brand,
+Jim Cromie, John P. Linderman, Karl Williamson, Nicholas Clark, Reini Urban,
+Steffen Müller, Stevan Little, Thorsten Glaser, Tony Cook.
+
+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 http://rt.perl.org/perlbug/ .  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 b5962c7134..1474e60903 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -2,544 +2,360 @@
 
 =head1 NAME
 
-perldelta - what is new for perl v5.15.4
+[ 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.15.5
 
 =head1 DESCRIPTION
 
-This document describes differences between the 5.15.3 release and
-the 5.15.4 release.
+This document describes differences between the 5.15.4 release and
+the 5.15.5 release.
 
 If you are upgrading from an earlier release such as 5.15.3, first read
-L<perl5153delta>, which describes differences between 5.15.3 and
+L<perl5154delta>, which describes differences between 5.15.3 and
 5.15.4.
 
-=head1 Core Enhancements
-
-=head2 $^X converted to an absolute path on FreeBSD, OS X and Solaris
+=head1 Notice
 
-C<$^X> is now converted to an absolute path on OS X, FreeBSD (without
-needing F</proc> mounted) and Solaris 10 and 11. This augments the
-previous approach of using F</proc> on Linux, FreeBSD and NetBSD
-(in all cases, where mounted).
+XXX Any important notices here
 
-This makes relocatable perl installations more useful on these platforms.
-(See "Relocatable @INC" in F<INSTALL>)
-
-=head2 Unicode Symbol Names
+=head1 Core Enhancements
 
-Perl now has proper support for Unicode in symbol names.  It used to be
-that C<*{$foo}> would ignore the internal UTF8 flag and use the bytes of
-the underlying representation to look up the symbol.  That meant that
-C<*{"\x{100}"}> and C<*{"\xc4\x80"}> would return the same thing.  All
-these parts of Perl have been fixed to account for Unicode:
+XXX New core language features go here. Summarise user-visible core language
+enhancements. Particularly prominent performance optimisations could go
+here, but most should go in the L</Performance Enhancements> section.
 
-=over
+[ List each enhancement as a =head2 entry ]
 
-=item *
+=head1 Security
 
-Method names (including those passed to C<use overload>)
+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.
 
-=item *
+[ List each security issue as a =head2 entry ]
 
-Typeglob names (including names of variables, subroutines and filehandles)
+=head1 Incompatible Changes
 
-=item *
+XXX For a release on a stable branch, this section aspires to be:
 
-Package names
+    There are no changes intentionally incompatible with 5.XXX.XXX
+    If any exist, they are bugs and reports are welcome.
 
-=item *
+[ List each incompatible change as a =head2 entry ]
 
-Constant subroutine names (not null-clean yet)
+=head1 Deprecations
 
-=item *
+XXX Any deprecated features, syntax, modules etc. should be listed here.
+In particular, deprecated modules should be listed here even if they are
+listed as an updated module in the L</Modules and Pragmata> section.
 
-C<goto>
+[ List each deprecation as a =head2 entry ]
 
-=item *
+=head1 Performance Enhancements
 
-Symbolic dereferencing
+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 ]
 
-Second argument to C<bless()> and C<tie()>
+=over 4
 
 =item *
 
-Return value of C<ref()>
+XXX
 
-=item *
+=back
 
-Package names returned by C<caller()>
+=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>, which prints stub
+entries to STDOUT.  Results can be pasted in place of the '=head2' entries
+below.  A paragraph summary for important changes should then be added by hand.
+In an ideal world, dual-life modules would have a F<Changes> file that could be
+cribbed.
 
-Subroutine prototypes
+[ Within each section, list entries as a =item entry ]
 
-=item *
+=head2 New Modules and Pragmata
 
-Attributes
+=over 4
 
 =item *
 
-Various warnings and error messages that mention variable names or values,
-methods, etc.
+XXX
 
 =back
 
-In addition, a parsing bug has been fixed that prevented C<*{é}> from
-implicitly quoting the name, but instead interpreted it as C<*{+é}>, which
-would cause a strict violation.
-
-C<*{"*a::b"}> automatically strips off the * if it is followed by an ASCII
-letter.  That has been extended to all Unicode identifier characters.
-
-C<$é> is now subject to "Used only once" warnings.  It used to be exempt,
-as it was treated as a punctuation variable.
-
-Also, single-character Unicode punctuation variables (like $‰) are now
-supported [perl #69032].  They are also supported with C<our> and C<my>,
-but that is a mistake that will be fixed before 5.16.
-
-=head2 Support for Embedded Nulls
-
-Some parts of Perl did not work correctly with nulls (C<chr 0>) embedded in
-strings.  That meant that, for instance, C<< $m = "a\0b"; foo->$m >> would
-call the "a" method, instead of the actual method name contained in $m.
-These parts of perl have been fixed to support nulls:
+=head2 Updated Modules and Pragmata
 
-=over
+=over 4
 
 =item *
 
-Method names
-
-=item *
+L<XXX> has been upgraded from version 0.69 to version 0.70.
 
-Typeglob names (including filehandle names)
+=back
 
-=item *
+=head2 Removed Modules and Pragmata
 
-Package names
+=over 4
 
 =item *
 
-Autoloading
+XXX
 
-=item *
+=back
 
-Return value of C<ref()>
+=head1 Documentation
 
-=item *
+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>.
 
-Package names returned by C<caller()>
+=head2 New Documentation
 
-=item *
+XXX Changes which create B<new> files in F<pod/> go here.
 
-Filehandle warnings
+=head3 L<XXX>
 
-=item *
+XXX Description of the purpose of the new file here
 
-Typeglob elements (C<*foo{"THING\0stuff"}>)
+=head2 Changes to Existing Documentation
 
-=item *
+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.
 
-Signal names
+=head3 L<XXX>
+
+=over 4
 
 =item *
 
-Various warnings and error messages that mention variable names or values,
-methods, etc.
+XXX Description of the change here
 
 =back
 
-One side effect of these changes is that blessing into "\0" no longer
-causes C<ref()> to return false.
+=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 Autoloaded sort Subroutines
+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.
 
-Custom sort subroutines can now be autoloaded [perl #30661]:
+[ Within each section, list entries as a =item entry that links to perldiag,
+  e.g.
 
-    sub AUTOLOAD { ... }
-    @sorted = sort foo @list; # uses AUTOLOAD
+  =item *
 
-=head2 Improved typemaps for Some Builtin Types
+  L<Invalid version object|perldiag/"Invalid version object">
+]
 
-Most XS authors will be aware that there is a longstanding bug
-in the OUTPUT typemap for T_AVREF (C<AV*>), T_HVREF (C<HV*>),
-T_CVREF (C<CV*>), and T_SVREF (C<SVREF> or C<\$foo>) that requires
-manually decrementing the reference count of the return value
-instead of the typemap taking care of this. For
-backwards-compatibility, this cannot be changed in the default
-typemaps. But we now provide additional typemaps
-C<T_AVREF_REFCOUNT_FIXED>, etc. that do not exhibit this bug.
-Using them in your extension is as simple as having one line
-in your C<TYPEMAP> section:
+=head2 New Diagnostics
 
-  HV*	T_HVREF_REFCOUNT_FIXED
+XXX Newly added diagnostic messages go here
 
-=head1 Performance Enhancements
+=head3 New Errors
 
 =over 4
 
 =item *
 
-C<substr> no longer calculates a value to return when called in void
-context.
+XXX L<message|perldiag/"message">
 
 =back
 
-=head1 Modules and Pragmata
-
-=head2 Updated Modules and Pragmata
+=head3 New Warnings
 
 =over 4
 
 =item *
 
-L<Archive::Tar> has been upgraded from version 1.78 to version 1.80.
+XXX L<message|perldiag/"message">
 
-=item *
+=back
 
-L<base> has been upgraded from version 2.17 to version 2.18.
+=head2 Changes to Existing Diagnostics
 
-C<base> no longer sets a module's C<$VERSION> to "-1" when a module it loads
-does not define a C<$VERSION>.  This change has been made because "-1" is not
-a valid version number under the new "lax" criteria used internally by
-C<UNIVERSAL::VERSION>.  (See L<version> for more on "lax" version criteria.)
+XXX Changes (i.e. rewording) of diagnostic messages go here
 
-C<base> no longer internally skips loading modules it has already loaded and
-instead relies on C<require> to inspect C<%INC>.  This fixes a bug when C<base>
-is used with code that clear C<%INC> to force a module to be reloaded.
+=over 4
 
 =item *
 
-L<Digest> has been upgraded from version 1.16 to version 1.17.
+XXX Describe change here
 
-=item *
+=back
 
-L<DynaLoader> has been upgraded from version 1.13 to 1.14.
+=head1 Utility Changes
 
-It stopped exporting its symbols with the ExtUtils::ParseXS changes in
-5.15.2.  Now it exports them once more.
+XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
+here. Most of these are built within the directories F<utils> and F<x2p>.
 
-=item *
+[ List utility changes as a =head3 entry for each utility and =item
+entries for each change
+Use L<XXX> with program names to get proper documentation linking. ]
 
-L<ExtUtils::MakeMaker> has been upgraded from version 6.59 to version 6.61_01.
-
-=item *
+=head3 L<XXX>
 
-L<ExtUtils::ParseXS> has been upgraded from version 3.04_04 to version 3.05.
+=over 4
 
 =item *
 
-L<Module::CoreList> has been upgraded from version 2.56 to 2.57.
+XXX
 
-=item *
+=back
 
-L<Module::Load> has been upgraded from version 0.20 to version 0.22.
+=head1 Configuration and Compilation
 
-Resolve possible security problem [http://goo.gl/YzHRU] where a '::' prefixed
-module can 'jump' out of @INC
+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.
 
-=item *
+[ List changes as a =item entry ].
 
-L<perlfaq> has been upgraded from version 5.0150034 to version 5.0150035.
+=over 4
 
 =item *
 
-L<Unicode::Collate> has been upgraded from version 0.78 to version 0.80.
-
-Locales updated to CLDR 2.0: ar, be, bg, ha, hr, kk, lt.
-Newly supported locales: as, fi__phonebook, gu, hi, kn, kok and ln.
+XXX
 
 =back
 
-=head1 Documentation
+=head1 Testing
 
-=head2 Changes to Existing Documentation
+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 summarising, although the bugs
+that they represent may be covered elsewhere.
 
-=head3 L<perlfunc>, L<open>
+[ List each test improvement as a =item entry ]
 
 =over 4
 
 =item *
 
-As an accident of history, C<open $fh, "<:", ...> applies the default
-layers for the platform (C<:raw> on Unix, C<:crlf> on Windows), ignoring
-whatever is declared by L<open.pm|open>.  This seems such a useful feature
-it has been documented in L<perlfunc|perlfunc/open> and L<open>.
+XXX
 
 =back
 
-=head3 L<perlapi>
-
-=over 4
-
-=item *
-
-The HV API has long accepted negative lengths to indicate that the key is
-in UTF8.  Now this is documented.
+=head1 Platform Support
 
-=item *
+XXX Any changes to platform support should be listed in the sections below.
 
-The C<boolSV()> macro is now documented.
+[ Within the sections, list each platform as a =item entry with specific
+changes as paragraphs below it. ]
 
-=back
+=head2 New Platforms
 
-=head3 L<perlguts>
+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 *
+=item XXX-some-platform
 
-A new section, L<Autoloading with XSUBs|perlguts/Autoloading with XSUBs>,
-has been added, which explains the two APIs for accessing the name of the
-autoloaded sub.
+XXX
 
 =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 Discontinued Platforms
 
-=head2 Changes to Existing Diagnostics
+XXX List any platforms that this version of perl no longer compiles on.
 
 =over 4
 
-=item *
+=item XXX-some-platform
 
-The message,
-"Code point 0x%X is not Unicode, no properties match it; all inverse
-prop erties do" has been changed to "Code point 0x%X is not Unicode, all
-\p{} matches fail; all \P{} matches succeed"
+XXX
 
 =back
 
-=head1 Testing
+=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.
 
 =over 4
 
-=item *
+=item XXX-some-platform
 
-F<t/porting/checkcfgvar.t> now tests that all config.sh-style files are
-complete. These are used by the various non-*nix to generate their
-F<config.h>, and an incomplete input file will generate invalid output.
+XXX
 
 =back
 
 =head1 Internal Changes
 
-=over 4
+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 *
-
-These new functions have been added as part of the work on Unicode symbols:
-
-    HvNAMELEN
-    HvNAMEUTF8
-    HvENAMELEN
-    HvENAMEUTF8
-    gv_init_pv
-    gv_init_pvn
-    gv_init_pvsv
-    gv_fetchmeth_pv
-    gv_fetchmeth_pvn
-    gv_fetchmeth_sv
-    gv_fetchmeth_pv_autoload
-    gv_fetchmeth_pvn_autoload
-    gv_fetchmeth_sv_autoload
-    gv_fetchmethod_pv_flags
-    gv_fetchmethod_pvn_flags
-    gv_fetchmethod_sv_flags
-    gv_autoload_pv
-    gv_autoload_pvn
-    gv_autoload_sv
-    newGVgen_flags
-    sv_derived_from_pv
-    sv_derived_from_pvn
-    sv_derived_from_sv
-    sv_does_pv
-    sv_does_pvn
-    sv_does_sv
-    whichsig_pv
-    whichsig_pvn
-    whichsig_sv
-
-The gv_fetchmethod_*_flags functions, like gv_fetchmethod_flags, are
-experimental and may change in a future release.
-
-=item *
+[ List each change as a =item entry ]
 
-The following functions were added.  These are I<not> part of the API:
-
-    GvNAMEUTF8
-    GvENAMELEN
-    GvENAME_HEK
-    CopSTASH_flags
-    CopSTASH_flags_set
-    PmopSTASH_flags
-    PmopSTASH_flags_set
-    sv_sethek
-    HEKfARG
-
-There is also a C<HEKf> macro corresponding to C<SVf>, for
-interpolating HEKs in formatted strings.
-
-=item *
-
-C<sv_catpvn_flags> takes a couple of new internal-only flags,
-C<SV_CATBYTES> and C<SV_CATUTF8>, which tell it whether the char array to
-be concatenated is UTF8.  This allows for more efficient concatenation than
-creating temporary SVs to pass to C<sv_catsv>.
-
-=item *
-
-For XS AUTOLOAD subs, $AUTOLOAD is set once more, as it was in 5.6.0.  This
-is in addition to setting C<SvPVX(cv)>, for compatibility with 5.8 to 5.14.
-See L<perlguts/Autoloading with XSUBs>.
+=over 4
 
 =item *
 
-Perl now checks whether the array (the linearised isa) returned by a MRO
-plugin begins with the name of the class itself, for which the array was
-created, instead of assuming that it does.  This prevents the first element
-from being skipped during method lookup.  It also means that
-C<mro::get_linear_isa> may return an array with one more element than the
-MRO plugin provided [perl #94306].
+XXX
 
 =back
 
 =head1 Selected Bug Fixes
 
-=over 4
-
-=item *
-
-In Perl 5.14.0, C<$tainted ~~ @array> stopped working properly.  Sometimes
-it would erroneously fail (when C<$tainted> contained a string that occurs
-in the array I<after> the first element) or erroneously succeed (when
-C<undef> occurred after the first element) [perl #93590].
-
-=item *
-
-Perl 5.15.0 introduced a minor regression, in that an object referenced by
-a deleted hash element would be able to access the freed element from its
-DESTROY method, causing panic errors [perl #99660].
-
-=item *
+XXX Important bug fixes in the core language are summarised here.
+Bug fixes in files in F<ext/> and F<lib/> are best summarised in
+L</Modules and Pragmata>.
 
-Functions in the CORE package can now be called as methods.  That used to
-work only when they had been called or referenced already.  So
-C<< "foo"->CORE::ucfirst >> returns Foo.
+[ List each fix as a =item entry ]
 
-=item *
-
-C<use> and C<require> are no longer affected by the I/O layers active in
-the caller's scope (enabled by L<open.pm|open>) [perl #96008].
-
-=item *
-
-Errors that occur when methods cannot be found during overloading now
-mention the correct package name, as they did in 5.8.x, instead of
-erroneously mentioning the "overload" package, as they have since 5.10.0.
-
-=item *
-
-Undefining C<%overload::> no longer causes a crash.
-
-=item *
-
-C<our $::é; $é> (which is invalid) no longer produces the "Compilation
-error at lib/utf8_heavy.pl..." error message, which it started emitting in
-5.10.0 [perl #99984].
-
-=item *
-
-A minor regression, introduced Perl 5.15.0, has been fixed in which some
-regular expression Unicode property matches (C<\p{...}>) matched
-non-Unicode code points.
-
-=item *
-
-In case-insensitive regular expression pattern matching, no longer on
-UTF-8 encoded strings does the scan for the start of match only look at
-the first possible position.  This caused matches such as
-C<"f\x{FB00}" =~ /ff/i> to fail.
-
-=item *
-
-On 64-bit systems, C<read()> now understands large string offsets beyond
-the 32-bit range.
-
-=item *
-
-Errors that occur when processing subroutine attributes no longer cause the
-subroutine's op tree to leak.
-
-=item *
-
-C<sort> now works once more with custom sort routines that are XSUBs.  It
-stopped working in 5.10.0.
+=over 4
 
 =item *
 
-C<sort> with a constant for a custom sort routine, although it produces
-unsorted results, no longer crashes.  It started crashing in 5.10.0.
+XXX
 
-=item *
+=back
 
-Warnings produced when a custom sort routine returns a non-numeric value
-now contain "in sort"; e.g., "Use of uninitialized value in sort".
+=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, unless
+they were specific to a particular platform (see below).
 
-C<< sort { $a <=> $b } >>, which is optimised internally, now produces
-"uninitialized" warnings for NaNs (not-a-number values), since C<< <=> >>
-returns C<undef> for those.  This brings it in line with
-S<C<< sort { 1; $a <=> $b } >>> and other more complex cases, which are not
-optimised [perl #94390].
+This is a list of some significant unfixed bugs, which are regressions
+from either 5.XXX.XXX or 5.XXX.XXX.
 
-=item *
+[ List each fix as a =item entry ]
 
-C<..> and C<...> in list context now call FETCH only once on tied
-arguments, instead of three or four times [perl #53554].
+=over 4
 
 =item *
 
-C<..> and C<...> in list context now mention the name of the variable in
-"uninitialized" warnings for string (as opposed to numeric) ranges.
+XXX
 
 =back
 
-=head1 Acknowledgements
-
-Perl 5.15.4 represents approximately 1 month of development since Perl 5.15.3
-and contains approximately 31,000 lines of changes across 350 files from 23
-authors.
+=head1 Obituary
 
-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.15.4:
+XXX If any significant core contributor has died, we've added a short obituary
+here.
 
-Alan Haggai Alavi, Brian Fraser, Chip Salzenberg, Chris 'BinGOs' Williams, Dave
-Rolsky, David Golden, David Mitchell, Dennis Kaarsemaker, Eric Brine, Father
-Chrysostomos, Florian Ragwitz, George Greer, Gerard Goossen, H.Merijn Brand,
-Jim Cromie, John P. Linderman, Karl Williamson, Nicholas Clark, Reini Urban,
-Steffen Müller, Stevan Little, Thorsten Glaser, Tony Cook.
-
-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.15.4..HEAD
 
 =head1 Reporting Bugs
 
diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template
index 89b4d35968..6247e92fab 100644
--- a/vms/descrip_mms.template
+++ b/vms/descrip_mms.template
@@ -345,7 +345,7 @@ x2p : [.x2p]$(DBG)a2p$(E) [.x2p]s2p.com [.x2p]find2perl.com
 extra.pods : miniperl
 	@ @extra_pods.com
 
-PERLDELTA_CURRENT = [.pod]perl5154delta.pod
+PERLDELTA_CURRENT = [.pod]perl5155delta.pod
 
 $(PERLDELTA_CURRENT) : [.pod]perldelta.pod
 	Copy/NoConfirm/Log $(MMS$SOURCE) $(MMS$TARGET)
diff --git a/win32/Makefile b/win32/Makefile
index 301f131258..63ea91925f 100644
--- a/win32/Makefile
+++ b/win32/Makefile
@@ -1073,7 +1073,7 @@ utils: $(PERLEXE) $(X2P)
 	copy ..\README.vmesa    ..\pod\perlvmesa.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5154delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5155delta.pod
 	cd ..\win32
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(PERLEXE) $(ICWD) ..\autodoc.pl ..
@@ -1166,7 +1166,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-cd $(PODDIR) && del /f *.html *.bat \
-	    perl5154delta.pod perlaix.pod perlamiga.pod perlapi.pod \
+	    perl5155delta.pod perlaix.pod perlamiga.pod perlapi.pod \
 	    perlbeos.pod perlbs2000.pod perlce.pod perlcn.pod \
 	    perlcygwin.pod perldgux.pod perldos.pod perlepoc.pod \
 	    perlfreebsd.pod perlhaiku.pod perlhpux.pod perlhurd.pod \
diff --git a/win32/makefile.mk b/win32/makefile.mk
index a689226d80..1a3daf2f4f 100644
--- a/win32/makefile.mk
+++ b/win32/makefile.mk
@@ -1259,7 +1259,7 @@ utils: $(PERLEXE) $(X2P)
 	copy ..\README.vmesa    ..\pod\perlvmesa.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5154delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5155delta.pod
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(PERLEXE) $(ICWD) ..\autodoc.pl ..
 	$(PERLEXE) $(ICWD) ..\pod\perlmodlib.pl -q
@@ -1351,7 +1351,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-cd $(PODDIR) && del /f *.html *.bat \
-	    perl5154delta.pod perlaix.pod perlamiga.pod perlapi.pod \
+	    perl5155delta.pod perlaix.pod perlamiga.pod perlapi.pod \
 	    perlbeos.pod perlbs2000.pod perlce.pod perlcn.pod \
 	    perlcygwin.pod perldgux.pod perldos.pod perlepoc.pod \
 	    perlfreebsd.pod perlhaiku.pod perlhpux.pod perlhurd.pod \
diff --git a/win32/pod.mak b/win32/pod.mak
index fac6afe453..6fb176de00 100644
--- a/win32/pod.mak
+++ b/win32/pod.mak
@@ -33,6 +33,7 @@ POD = perl.pod	\
 	perl5152delta.pod	\
 	perl5153delta.pod	\
 	perl5154delta.pod	\
+	perl5155delta.pod	\
 	perl561delta.pod	\
 	perl56delta.pod	\
 	perl581delta.pod	\
@@ -155,6 +156,7 @@ MAN = perl.man	\
 	perl5152delta.man	\
 	perl5153delta.man	\
 	perl5154delta.man	\
+	perl5155delta.man	\
 	perl561delta.man	\
 	perl56delta.man	\
 	perl581delta.man	\
@@ -277,6 +279,7 @@ HTML = perl.html	\
 	perl5152delta.html	\
 	perl5153delta.html	\
 	perl5154delta.html	\
+	perl5155delta.html	\
 	perl561delta.html	\
 	perl56delta.html	\
 	perl581delta.html	\
@@ -399,6 +402,7 @@ TEX = perl.tex	\
 	perl5152delta.tex	\
 	perl5153delta.tex	\
 	perl5154delta.tex	\
+	perl5155delta.tex	\
 	perl561delta.tex	\
 	perl56delta.tex	\
 	perl581delta.tex	\