This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta: removed confusing XSLoader commentary
[perl5.git] / pod / perldelta.pod
index 8e46a51..f186a04 100644 (file)
@@ -2,44 +2,28 @@
 
 =head1 NAME
 
-[ 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.0
 
-=for comment
-This has been completed up to 571f0e8.
-
 =head1 DESCRIPTION
 
 This document describes differences between the 5.15.0 release and
 the 5.14.0 release.
 
-If you are upgrading from an earlier release such as 5.YYY.YYY, first read
-L<perl5YYYdelta>, which describes differences between 5.ZZZ.ZZZ and
-5.YYY.YYY.
+If you are upgrading from an earlier release such as 5.12.0, first read
+L<perl5140delta>, which describes differences between 5.12.0 and
+5.14.0.
 
 Some of the changes have been included in Perl 5.14.1.  These are
 indicated with a "(5.14.1)" marker.
 
-XXX compare this perldelta to 5.14.1 and double check the notation
-
-=head1 Notice
-
-XXX Any important notices here
-
 =head1 Core Enhancements
 
-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.
-
-[ List each enhancement as a =head2 entry ]
-
 =head2 C<CORE::> works on all keywords
 
 The C<CORE::> prefix can now be used on keywords enabled by
-L<feature.pm|feature>, even outside the scope of C<use feature>.
+L<feature.pm|feature>, even outside the scope of C<use feature>.  Relevant
+documentation files L<CORE>, L<feature>, L<perlfunc>, L<perlsub>, and
+L<perlsyn> have been updated.
 
 =head2 C<continue> no longer requires the "switch" feature
 
@@ -76,16 +60,10 @@ L<perldebug/"b [file]:[line] [condition]">.
 
 =head1 Security
 
-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.
-
-[ List each security issue as a =head2 entry ]
+No changes since 5.14.0.
 
 =head1 Incompatible Changes
 
-[ List each incompatible change as a =head2 entry ]
-
 =head2 Tying scalars that hold typeglobs
 
 Attempting to tie a scalar after a typeglob was assigned to it would
@@ -115,57 +93,35 @@ deleted entirely.
 Previously, if one embeds Perl or uses XS and calls fork(3) from C, Perls
 notion of C<$$> could go out of sync with what getpid() returns. By always
 fetching the value of C<$$> via getpid(), this potential bug is eliminated.
-Code that depends on the caching behavior will break.  As describe in L</Core
-Enhancements>, C<$$> is now writeable, but it will be reset during a fork.
+Code that depends on the caching behavior will break.  As described in
+L</Core Enhancements>, C<$$> is now writable, but it will be reset during a
+fork.
 
 =head1 Deprecations
 
-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.
-
-[ List each deprecation as a =head2 entry ]
+There have been no deprecations since 5.14.0.
 
 =head1 Performance Enhancements
 
-XXX Changes which enhance performance without changing behaviour go here. There
-may well be none in a stable release.
-
-[ List each enhancement as a =item entry ]
-
-=over 4
-
-=item *
-
-XXX
-
-=back
+There are no benchmarked enhancements since 5.14.0.
 
 =head1 Modules and Pragmata
 
-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.
+=head2 New Modules and Pragmata
 
-[ Within each section, list entries as a =item entry ]
+None.
 
-=head2 New Modules and Pragmata
+=head2 Updated Modules and Pragmata
 
 =over 4
 
 =item *
 
-XXX
+L<charnames> has been updated from version 1.18 to version 1.22
 
-=back
-
-=head2 Updated Modules and Pragmata
-
-=over 4
+L<charnames> can now be invoked with a new option, C<:loose>,
+which is like the existing C<:full> option, but enables Unicode loose
+name matching.  Details are in L<charnames/LOOSE MATCHES>.
 
 =item *
 
@@ -189,7 +145,8 @@ L<B> has been upgraded from version 1.29 to version 1.30.
 
 =item *
 
-L<B::Deparse> has been upgraded from version 1.03 to 1.05.
+L<B::Deparse> has been upgraded from version 1.03 to 1.05. (Perl 5.14.1
+had version 1.04.)
 
 It addresses two regressions in Perl 5.14.0:
 
@@ -198,7 +155,7 @@ It addresses two regressions in Perl 5.14.0:
 =item *
 
 Deparsing of the C<glob> operator and its diamond (C<< <> >>) form now
-works again [RT #90898] (5.14.1).
+works again [perl #90898] (5.14.1).
 
 =item *
 
@@ -214,7 +171,7 @@ Plus a few other bugs:
 =item *
 
 Deparsing of handle C<keys>, C<each> and C<value> with a scalar argument
-now works [RT #91008].
+now works [perl #91008].
 
 =item *
 
@@ -229,7 +186,7 @@ conflict with user-defined subroutines.
 =item *
 
 Deparsing assignment to an lvalue method specified as a variable
-(C<< $obj->$method = ... >>) used not to work [RT #62498].
+(C<< $obj->$method = ... >>) used not to work [perl #62498].
 
 =back
 
@@ -337,8 +294,8 @@ L<IPC::Open3> has been upgraded from version 1.10 to version 1.11.
 
 =item *
 
-Fixes a bug which prevented use of open3 on Windows when *STDIN, *STDOUT or
-*STDERR had been localized.
+Fixes a bug which prevented use of C<open3> on Windows when C<*STDIN>,
+C<*STDOUT> or C<*STDERR> had been localized.
 
 =item *
 
@@ -365,17 +322,17 @@ Math::BigFloat).
 
 =item *
 
-L<Math::Complex> has been upgraded from version 1.56 to version 1.57.
+L<Math::Complex> has been upgraded from version 1.56 to version 1.57
+and L<Math::Trig> has been upgraded from version 1.20 to version 1.21.
 
-Correct copy constructor usage.
-Fix polarwise formatting with numeric format specifier.
-More stable C<great_circle_direction> algorithm.
+Fixes include: correct copy constructor usage; fix polarwise formatting with
+numeric format specifier; and more stable C<great_circle_direction> algorithm.
 
 =item *
 
-L<Module::CoreList> has been upgraded from version 2.49 to 2.50.
+L<Module::CoreList> has been upgraded from version 2.49 to 2.51.
 
-Updated for v5.12.4.
+Updated for v5.12.4, v5.14.1 and v5.15.0
 
 =item *
 
@@ -406,17 +363,13 @@ It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if
 C<$scalar> is a copy-on-write scalar.
 
 It also fixes a hang that occurs with C<readline> or C<< <$fh> >> if a
-typeglob has been assigned to $scalar [RT #92258].
+typeglob has been assigned to $scalar [perl #92258].
 
 =item *
 
-XXX If any changes are made, the version will need to be bumped again.
-What blead has is currently (as of a9d1f3db, 7th of June) identical to
-5.14.1's version.
+L<Pod::Perldoc> has been upgraded from version 3.15_03 to 3.15_05.
 
-L<Pod::Perldoc> has been upgraded from version 3.15_03 to 3.15_04.
-
-It corrects the search paths on VMS [RT #90640].
+It corrects the search paths on VMS [perl #90640]. (5.14.1)
 
 =item *
 
@@ -447,26 +400,12 @@ Updated to CLDR 1.9.1
 
 L<Unicode::Normalize> has been upgraded from version 1.10 to version 1.12
 
-Fixes for the removal of C<unicore/CompositionExclusions.txt> from core.
+Fixes for the removal of F<unicore/CompositionExclusions.txt> from core.
 
 =item *
 
 L<XSLoader> has been upgraded from version 0.13 to version 0.15
 
-Integrated changes from bleadperl
-
-=item *
-
-L<charnames> can now be invoked with a new option, C<:loose>,
-which is like the existing C<:full> option, but enables Unicode loose
-name matching.  This means that instead of
-having to get the name of the code point or sequence you want exactly right,
-you can fudge things somewhat.  This is especially useful when
-you don't remember if the official Unicode name uses hyphens or
-blanks between words.  Details are in L<charnames/LOOSE MATCHES>.
-
-XXX
-
 =back
 
 =head2 Removed Modules and Pragmata
@@ -489,30 +428,19 @@ C<Shell> has been removed from the Perl core.  Prior version was 0.72_01.
 
 =head1 Documentation
 
-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>.
-
 =head2 New Documentation
 
-XXX Changes which create B<new> files in F<pod/> go here.
-
-=head3 L<XXX>
-
-XXX Description of the purpose of the new file here
+None.
 
 =head2 Changes to Existing Documentation
 
-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<perlfork>
 
 =over
 
 =item *
 
-Added portability caveats related to using kill on forked process.
+Added portability caveats related to using C<kill> on forked process.
 
 =back
 
@@ -522,6 +450,10 @@ Added portability caveats related to using kill on forked process.
 
 =item *
 
+Documentation for C<use> now includes a pointer to F<if.pm> (5.14.1)
+
+=item *
+
 C<given>, C<when> and C<default> are now listed in L<perlfunc> (5.14.1).
 
 =item *
@@ -539,7 +471,7 @@ handles.
 
 Some of the function descriptions in L<perlguts> were confusing, as it was
 not clear whether they referred to the function above or below the
-description.  This has been clarified [RT #91790].
+description.  This has been clarified [perl #91790].
 
 =back
 
@@ -562,7 +494,7 @@ syntax introduced in Perl 5.14.0 (5.14.1).
 
 L<perlmod> now states explicitly that some types of explicit symbol table
 manipulation are not supported.  This codifies what was effectively already
-the case [RT #78074].
+the case [perl #78074].
 
 =back
 
@@ -607,6 +539,17 @@ they have been edited.
 
 =back
 
+=head3 L<perlsub>
+
+=over
+
+=item *
+
+The L<perlsub/"Lvalue subroutines"> section has been amended to reflect
+changes and bug fixes introduced in Perl 5.15.0.
+
+=back
+
 =head3 L<perlre>
 
 =over
@@ -630,6 +573,16 @@ on environment variables has been corrected and expanded (5.14.1).
 
 =back
 
+=head3 L<perltie>
+
+=over
+
+=item *
+
+Documented the required syntax for tying handles.
+
+=back
+
 =head3 L<perlvar>
 
 =over
@@ -639,7 +592,12 @@ on environment variables has been corrected and expanded (5.14.1).
 The documentation for L<$!|perlvar/$!> has been corrected and clarified.
 It used to state that $! could be C<undef>, which is not the case.  It was
 also unclear as to whether system calls set C's C<errno> or Perl's C<$!>
-[RT #91614].
+[perl #91614].
+
+=item *
+
+Documentation for L<$$|perlvar/$$> has been amended with additional
+cautions regarding changing the process ID. 
 
 =back
 
@@ -661,15 +619,8 @@ 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>.
 
-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.
-
-[ Within each section, list entries as a =item entry ]
-
 =head2 New Diagnostics
 
-XXX Newly added diagnostic messages go here
-
 =head3 New Warnings
 
 =over 4
@@ -677,50 +628,20 @@ XXX Newly added diagnostic messages go here
 =item L<Useless assignment to a temporary|perldiag/"Useless assignment to a temporary">
 
 Assigning to a temporary returned from an XS lvalue subroutine now produces a
-warning [RT #31946].
+warning [perl #31946].
 
 =back
 
 =head2 Changes to Existing Diagnostics
 
-XXX Changes (i.e. rewording) of diagnostic messages go here
-
-=over 4
-
-=item *
-
-XXX
-
-=back
+None.
 
 =head1 Utility Changes
 
-XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
-here. Most of these are built within the directories F<utils> and F<x2p>.
-
-[ 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. ]
-
-=head3 L<XXX>
-
-=over 4
-
-=item *
-
-XXX
-
-=back
+None.
 
 =head1 Configuration and Compilation
 
-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.
-
-[ List changes as a =item entry ].
-
 =over 4
 
 =item *
@@ -741,43 +662,48 @@ into F<ext/IPC-Open3>, as C<IPC::Open2::open2()> is implemented as a thin
 wrapper around C<IPC::Open3::_open3()>, and hence is very tightly coupled to
 it.
 
-=back
-
-=head1 Testing
+=item *
 
-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.
+The magic types and magic vtables are now generated from data in a new script
+F<regen/mg_vtable.pl>, instead of being maintained by hand. As different EBCDIC
+variants can't agree on the code point for '~', the character to code point
+conversion is done at build time by F<generate_uudmap> to a new generated header
+F<mg_data.h>. C<PL_vtbl_bm> and C<PL_vtbl_fm> are now defined by the
+pre-processor as C<PL_vtbl_regexp>, instead of being distinct C variables.
+C<PL_vtbl_sig> has been removed.
 
-[ List each test improvement as a =item entry ]
+=item *
 
-=over 4
+Building with C<-DPERL_GLOBAL_STRUCT> works again. This configuration is not
+generally used.
 
 =item *
 
-XXX
+Perl configured with I<MAD> now correctly frees C<MADPROP> structures when
+OPs are freed. C<MADPROP>s are now allocated with C<PerlMemShared_malloc()>
 
 =back
 
-=head1 Platform Support
+=head1 Testing
 
-XXX Any changes to platform support should be listed in the sections below.
+There have been no significant changes to the process for testing a
+newly-built perl.
 
-[ Within the sections, list each platform as a =item entry with specific
-changes as paragraphs below it. ]
+See the source code commit history for changes to individual test files.
+
+=head1 Platform Support
 
 =head2 New Platforms
 
-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.
+None.
 
-=over 4
+=head2 Discontinued Platforms
+
+None.
+
+=head2 Platform-Specific Notes
 
-=item GNU/Hurd
+=head3 GNU/Hurd
 
 =over
 
@@ -788,40 +714,41 @@ on GNU/Hurd.  C.f. Bug-Debian: http://bugs.debian.org/587901
 
 =back
 
-=item Mac OS X
+=head3 Mac OS X
 
-Clarified apple developer tools requirements in README.macosx
+=over
 
-=item MSWin32
+=item *
 
-Supplied F<makefile.mk> patched to support gcc-4.x.x and README.win32
-updated accordingly. [RT #91354]
+Clarified Apple Developer Tools requirements in F<README.macosx>
 
-=item Solaris
+=item *
 
-Updated the list of required packages for building perl to reflect Solaris 9
-and 10 in README.solaris [RT #90850]
+Mac OS X specific compilation instructions have been clarified (5.14.1)
 
 =back
 
-=head2 Discontinued Platforms
-
-XXX List any platforms that this version of perl no longer compiles on.
+=head3 MSWin32
 
-=over 4
+=over
 
-=item XXX-some-platform
+=item *
 
-XXX
+Supplied F<makefile.mk> patched to support gcc-4.x.x and README.win32
+updated accordingly. [perl #91354]
 
 =back
 
-=head2 Platform-Specific Notes
+=head3 Solaris
 
-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
+
+=item *
+
+Updated the list of required packages for building perl to reflect Solaris 9
+and 10 in README.solaris [perl #90850] (5.14.1)
+
+=back
 
 =head3 Ubuntu Linux
 
@@ -830,49 +757,46 @@ L</Modules and Pragmata> section.
 =item *
 
 The L<ODBM_File> installation process has been updated with the new library
-paths on Ubuntu natty [RT #90106].
+paths on Ubuntu natty [perl #90106] (5.14.1)
 
 =item *
 
 I<h2ph> now gets the include paths from gcc correctly.  This stopped
-working when Ubuntu switched to a "multiarch" setup [RT #90122].
+working when Ubuntu switched to a "multiarch" setup [perl #90122].
 
 =back
 
 =head1 Internal Changes
 
-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.
-
 =over 4
 
 =item *
 
-When empting a hash of its elements (e.g. via undef(%h), or %h=()), HvARRAY
-field is no longer temporarily zeroed.  Any destructors called on the freed
-elements see the remaining elements. Thus, %h=() becomes more like C<delete
-$h{$_} for keys %h>.
+The compiled representation of formats is now stored via the C<mg_ptr> of
+their C<PERL_MAGIC_fm>. Previously it was stored in the string buffer,
+beyond C<SvLEN()>, the regular end of the string. C<SvCOMPILED()> and
+C<SvCOMPILED_{on,off}()> now exist solely for compatibility for XS code.
+The first is always 0, the other two now no-ops. (5.14.1)
 
 =item *
 
-The compiled representation of formats is now stored via the mg_ptr of
-their PERL_MAGIC_fm. Previously it was stored in the string buffer,
-beyond SvLEN(), the regular end of the string. SvCOMPILED() and
-SvCOMPILED_{on,off}() now exist solely for compatibility for XS code.
-The first is always 0, the other two now no-ops.
+Some global variables have been marked C<const>, members in the interpreter
+structure have been re-ordered, and the opcodes have been re-ordered. The op
+C<OP_AELEMFAST> has been split into C<OP_AELEMFAST> and C<OP_AELEMFAST_LEX>.
 
 =item *
 
-Boyer-Moore compiled scalars are now PVMGs, and the Boyer-Moore tables are now
-stored via the mg_ptr of their PERL_MAGIC_bm. Previously they were PVGVs, with
-the tables stored in the string buffer, beyond SvLEN(). This eliminates the
-last place where the core stores data beyond SvLEN().
+When empting a hash of its elements (e.g. via undef(%h), or %h=()), HvARRAY
+field is no longer temporarily zeroed.  Any destructors called on the freed
+elements see the remaining elements. Thus, %h=() becomes more like C<delete
+$h{$_} for keys %h>.
 
 =item *
 
-C<pos> in lvalue context now returns a PVMG instead of a PVLV, storing the
-target SV in C<mg_obj>, instead of C<LvTARG()>.
+Boyer-Moore compiled scalars are now PVMGs, and the Boyer-Moore tables are now
+stored via the mg_ptr of their C<PERL_MAGIC_bm>. Previously they were PVGVs,
+with the tables stored in the string buffer, beyond C<SvLEN()>. This eliminates
+the last place where the core stores data beyond C<SvLEN()>.
 
 =item *
 
@@ -903,12 +827,6 @@ on read only values, or SVs which already have the unknown magic type.
 
 =head1 Selected Bug Fixes
 
-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>.
-
-[ List each fix as a =item entry ]
-
 =head2 Regular expressions and character classes
 
 =over 4
@@ -927,7 +845,7 @@ succeeded inappropriately.  This is now fixed.
 =item *
 
 5.14.0 introduced some memory leaks in regular expression character
-classes such as C<[\w\s]>, which have now been fixed
+classes such as C<[\w\s]>, which have now been fixed (5.14.1)
 
 =item *
 
@@ -940,7 +858,7 @@ portion of the fold, plus some more.
 
  "s\N{U+DF}" =~ /[\x{DF}foo]/i
 
-is one such case.  C<\xDF> folds to C<"ss">
+is one such case.  C<\xDF> folds to C<"ss">. (5.14.1)
 
 =item *
 
@@ -977,19 +895,19 @@ A number of edge cases have been fixed with formats and C<formline>;
 in particular, where the format itself is potentially variable (such as
 with ties and overloading), and where the format and data differ in their
 encoding. In both these cases, it used to possible for the output to be
-corrupted [RT #91032].
+corrupted [perl #91032].
 
 =item *
 
 C<formline> no longer converts its argument into a string in-place.  So
 passing a reference to C<formline> no longer destroys the reference
-[RT #79532].
+[perl #79532].
 
 =back
 
 =head2 Copy-on-write scalars
 
-Copy-on-write scalars were introduced in 5.6.0, but most Perl code
+Copy-on-write scalars were introduced in 5.8.0, but most Perl code
 did not encounter them (they were used mostly internally).  Perl
 5.10.0 extended them, such that assigning C<__PACKAGE__> or a
 hash key to a scalar would make it copy-on-write.  Several parts
@@ -1001,7 +919,7 @@ of Perl were not updated to account for them, but have now been fixed.
 
 C<utf8::decode> had a nasty bug that would modify copy-on-write scalars'
 string buffers in place (i.e., skipping the copy).  This could result in
-hashes having two elements with the same key [RT #91834].
+hashes having two elements with the same key [perl #91834].
 
 =item *
 
@@ -1036,7 +954,7 @@ There have been various fixes to lvalue subroutines.
 =item *
 
 Explicit return now returns the actual argument passed to return, instead
-of copying it [RT #72724] [RT #72706].
+of copying it [perl #72724] [perl #72706].
 
 B<Note:> There are still some discrepancies between explicit and implicit
 return, which will hopefully be resolved soon.  So the exact behaviour is
@@ -1053,7 +971,7 @@ this restriction has been lifted.
 
 Lvalue subroutines are less restrictive as to what values can be returned.
 It used to croak on values returned by C<shift> and C<delete> and from
-other subroutines, but no longer does so [RT #71172].
+other subroutines, but no longer does so [perl #71172].
 
 =item *
 
@@ -1065,14 +983,14 @@ Perl 5.8.2.  Now lvalue subroutines have been likewise fixed.
 
 Lvalue subroutines used to copy their return values in rvalue context.  Not
 only was this a waste of CPU cycles, but it also caused bugs.  A C<($)>
-prototype would cause an lvalue sub to copy its return value [RT #51408],
+prototype would cause an lvalue sub to copy its return value [perl #51408],
 and C<while(lvalue_sub() =~ m/.../g) { ... }> would loop endlessly
-[RT #78680].
+[perl #78680].
 
 =item *
 
 Autovivification now works on values returned from lvalue subroutines
-[RT #7946].
+[perl #7946].
 
 =item *
 
@@ -1083,13 +1001,25 @@ happen.  This could result in "Bizarre copy of ARRAY" errors or C<print>
 ignoring its arguments.  It also made nonsensical code like C<@{\$_}> "work".
 This was fixed in 5.14.0 if an array were the first thing returned from the
 subroutine (but not for C<$scalar, @array> or hashes being returned).  Now a
-more general fix has been applied [RT #23790].
+more general fix has been applied [perl #23790].
+
+=item *
+
+When called in pass-by-reference context, lvalue subroutines used to copy
+any read-only value that was returned.  E.g., C< sub :lvalue { $] } >
+would not return C<$]>, but a copy of it.
 
 =item *
 
 Assignment to C<keys> returned from an lvalue sub used not to work, but now
 it does.
 
+=item *
+
+Applying the C<:lvalue> attribute to an XSUB or to an aliased subroutine
+stub with C<< sub foo :lvalue; >> syntax stopped working in Perl 5.12.
+This has been fixed.
+
 =back
 
 =head2 Fixes related to hashes
@@ -1100,18 +1030,18 @@ it does.
 
 A bug has been fixed that would cause a "Use of freed value in iteration"
 error if the next two hash elements that would be iterated over are
-deleted [RT #85026].
+deleted [perl #85026]. (5.14.1)
 
 =item *
 
-Freeing deeply nested hashes no longer crashes [RT #44225].
+Freeing deeply nested hashes no longer crashes [perl #44225].
 
 =item *
 
 Deleting the current hash iterator (the hash element that would be returend
 by the next call to C<each>) in void context used not to free it.  The hash
 would continue to reference it until the next iteration.  This has been
-fixed [RT #85026].
+fixed [perl #85026].
 
 =back
 
@@ -1122,7 +1052,7 @@ fixed [RT #85026].
 =item *
 
 Passing the same constant subroutine to both C<index> and C<formline> no
-longer causes one or the other to fail [RT #89218].
+longer causes one or the other to fail [perl #89218]. (5.14.1)
 
 =item *
 
@@ -1134,7 +1064,7 @@ It has now been fixed.
 
 Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
 a pack template equivalent to "U0" if the input string was empty.  This has
-been fixed [RT #90160].
+been fixed [perl #90160].
 
 =item *
 
@@ -1145,7 +1075,7 @@ blessed variable (C<bless \my @a; sub foo { @a }>).
 
 Now there is an extra pass during global destruction to fire destructors on
 any objects that might be left after the usual passes that check for
-objects referenced by scalars [RT #36347].
+objects referenced by scalars [perl #36347].
 
 This bug fix was added in Perl 5.13.9, but caused problems with some CPAN
 modules that were relying on the bug.  Since it was so close to Perl
@@ -1158,18 +1088,18 @@ below).
 C<given> was not calling set-magic on the implicit lexical C<$_> that it
 uses.  This meant, for example, that C<pos> would be remembered from one
 execution of the same C<given> block to the next, even if the input were a
-different variable [RT #84526].
+different variable [perl #84526].
 
 =item *
 
 The "R" command for restarting a debugger session has been fixed to work on
 Windows, or any other system lacking a C<POSIX::_SC_OPEN_MAX> constant
-[RT #87740].
+[perl #87740].
 
 =item *
 
 Fixed a case where it was possible that a freed buffer may have been read
-from when parsing a here document [RT #90128].
+from when parsing a here document [perl #90128]. (5.14.1)
 
 =item *
 
@@ -1179,20 +1109,20 @@ The C<study> function could become confused if fed a string longer than
 =item *
 
 C<each(I<ARRAY>)> is now wrapped in C<defined(...)>, like C<each(I<HASH>)>,
-inside a C<when> condition [RT #90888].
+inside a C<while> condition [perl #90888].
 
 =item *
 
 In @INC filters (subroutines returned by subroutines in @INC), $_ used to
 misbehave: If returned from a subroutine, it would not be copied, but the
 variable itself would be returned; and freeing $_ (e.g., with C<undef *_>)
-would cause perl to crash.  This has been fixed [RT #91880].
+would cause perl to crash.  This has been fixed [perl #91880].
 
 =item *
 
 An ASCII single quote (') in a symbol name is meant to be equivalent to a
 double colon (::) except at the end of the name.  It was not equivalent if
-followed by a null character, but now it is [RT #88138].
+followed by a null character, but now it is [perl #88138].
 
 =item *
 
@@ -1208,53 +1138,79 @@ vianame(), and string_vianame().
 =item *
 
 Some cases of threads crashing due to memory allocation during cloning have
-been fixed [RT #90006].
+been fixed [perl #90006].
 
 =item *
 
 Attempting to C<goto> out of a tied handle method used to cause memory
 corruption or crashes.  Now it produces an error message instead
-[RT #8611].
-
-=back
+[perl #8611].
 
-=head2 Additional fixes by ticket number
-
-XXX Prefix these with "\n=item *\n" once the list is final
+=item *
 
-Fixed RT #88822: Test failure t/re_fold_grind.t with bleadperl
-Fixed RT #89896: Locale::Maketext test failure
+Perl skips copying values returned from a subroutine if it thinks the value
+is not in use elsewhere.  Due to faulty logic, this would happen with the
+result of C<delete>, C<shift> or C<splice>, even if the result was
+referenced elsewhere.  So C<< \sub { delete $_[0] }->($x) >> would return a
+reference to C<$x>.  This has been fixed [perl #91844].
 
-XXX Comments from FC: I do not think these two are necessary.
+=back
 
 =head1 Known Problems
 
-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).
+=over 4
 
-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 ]
+The fix for perl #36347 causes test failures for C<Gtk2> and C<Tk> on some
+systems [perl #82542].
 
-=over 4
+=item *
+
+The changes to C<tie> cause test failures for the C<JS> module.
 
 =item *
 
-The fix for RT #36347 causes test failures for C<Gtk2> and C<Tk> on some
-systems [RT #82542].
+The changes to C<$$> cause test failures for the C<Event> module.
 
 =back
 
-=head1 Obituary
-
-XXX If any significant core contributor has died, we've added a short obituary
-here.
 
 =head1 Acknowledgements
 
-XXX The list of people to thank goes here.
+Perl 5.15.0 represents approximatly five weeks of development since Perl
+5.14.0 and contains approximately 54,000 lines of changes across 618
+files from 57 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.0:
+
+Alan Haggai Alavi, Bo Johansson, Bo Lindbergh, brian d foy, Chia-liang
+Kao, Chris 'BinGOs' Williams, Claudio Ramirez, Craig A. Berry, David
+Golden, David Leadbeater, David Mitchell, Dennis Kaarsemaker, Dominic
+Hargreaves, Eric Brine, Father Chrysostomos, Florian Ragwitz, George
+Greer, Gisle Aas, H.Merijn Brand, Hojung Yoon, Ian Goodacre, Jesse
+Vincent, Jim Cromie, Johan Vromans, John Hawkinson, John P. Linderman,
+Joshua ben Jore, Karl Williamson, Kevin J.  Woolley, Leo Lapworth, Leon
+Brocard, Leon Timmermans, Louis Strous, Marcel Grünauer, Martin Hasch,
+Max Maischein, Michael Witten, Moritz Lenz, Nicholas Clark, Niko Tyni,
+Nuno Carvalho, Pau Amma, Peter John Acklam, Robin Barker, Salvador
+Fandiño, Samuel Thibault, Shawn M Moore, Shigeya Suzuki, Shlomi Fish,
+Sisyphus, Steffen Müller, Todd Rinaldo, Tom Christiansen, Tony Cook,
+Vladimir Timofeev, Zefram and Zsbán Ambrus.
+
+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
 
@@ -1272,7 +1228,8 @@ 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 be able
+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