--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+perl5170delta - what is new for perl v5.17.0
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.16.0 release and
+the 5.17.0 release.
+
+If you are upgrading from an earlier release such as 5.16.0, first read
+L<perl5160delta>, which describes differences between 5.14.0 and
+5.16.0.
+
+=head1 Incompatible Changes
+
+=head2 qw(...) can no longer be used as parentheses
+
+C<qw> lists used to fool the parser into thinking they were always
+surrounded by parentheses. This permitted some surprising constructions
+such as C<foreach $x qw(a b c) {...}>, which should really be written
+C<foreach $x (qw(a b c)) {...}>. These would sometimes get the lexer into
+the wrong state, so they didn't fully work, and the similar C<foreach qw(a
+b c) {...}> that one might expect to be permitted never worked at all.
+
+This side effect of C<qw> has now been abolished. It has been deprecated
+since Perl 5.13.11. It is now necessary to use real parentheses
+everywhere that the grammar calls for them.
+
+=head2 C<\s> in regular expressions now matches a Vertical Tab (experimental)
+
+This is an experiment early in the development cycle to see what
+repercussions arise from this change. It may well be that we decide
+to require a C<"use feature"> to activate this behavior. Because
+of the experimental nature of this, which may be reversed, the
+documentation has not been changed to reflect it.
+
+=head1 Deprecations
+
+=head2 Unescaped braces in regexps
+
+Literal unescaped C<{> in regular expressions is now deprecated. Every
+brace character should be either escaped (by a preceding backslash) or
+part of a construct where it's a metacharacter. This catches likely typos
+such as C</f{,3}/>. It will also allow braces to be used in the future
+to delimit parameters to metacharacters that currently take no parameters.
+
+=head1 Performance Enhancements
+
+=over 4
+
+=item *
+
+Filetest ops manage the stack in a fractionally more efficient manner.
+
+=item *
+
+Globs used in a numeric context are now numerified directly in most cases,
+rather than being numerified via stringification.
+
+=back
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<B> has been upgraded from version 1.34 to 1.35.
+
+The C<stashlen> method of COPs has been added. This provides access to an
+internal field added in perl 5.16 under threaded builds [perl #113034].
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded from version 3.16 to 3.17.
+
+The generated C code now avoids unnecessarily incrementing
+C<PL_amagic_generation> on Perl versions where it's done automatically
+(or on current Perl where the variable no longer exists).
+
+=item *
+
+L<File::DosGlob> has been upgraded from version 1.06 to 1.07.
+
+Small documentation and comment fixes.
+
+=item *
+
+L<File::Find> has been upgraded from version 1.20 to 1.21.
+
+Individual files may now appear in list of directories to be searched
+[perl #59750].
+
+=item *
+
+L<File::stat> has been upgraded from version 1.05 to 1.06.
+
+C<File::stat> ignores the L<filetest> pragma, and warns when used in
+combination therewith. But it was not warning for C<-r>. This has been
+fixed [perl #111640].
+
+C<-p> now works, and does not return false for pipes [perl #111638].
+
+=item *
+
+L<Hash::Util> has been upgraded from version 0.11 to 0.12.
+
+C<hash_unlocked> and C<hashref_unlocked> now returns true if the hash is
+unlocked, instead of always returning false [perl #112126].
+
+C<hash_unlocked>, C<hashref_unlocked>, C<lock_hash_recurse> and
+C<unlock_hash_recurse> are now exportable [perl #112126].
+
+Two new functions, C<hash_locked> and C<hashref_locked>, have been added.
+Oddly enough, these two functions were already exported, even though they
+did not exist [perl #112126].
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.66 to 2.67.
+
+=item *
+
+L<overload> has been upgraded from version 1.18 to 1.19.
+
+C<no overload> now warns for invalid arguments, just like C<use overload>.
+
+=item *
+
+L<Pod::Functions> has been upgraded from version 1.05 to 1.06.
+
+Typo fix in generated documentation.
+
+=item *
+
+L<Storable> has been upgraded from version 2.34 to 2.35.
+
+Modifying C<$_[0]> within C<STORABLE_freeze> no longer results in crashes
+[perl #112358].
+
+An object whose class implements C<STORABLE_attach> is now thawed only once
+when there are multiple references to it in the structure being thawed
+[perl #111918].
+
+=item *
+
+L<utf8> has been upgraded from version 1.09 to 1.10.
+
+Some documentation has been clarified.
+
+=back
+
+=head2 Removed Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Version::Requirements> has been removed from the core distribution. It is
+available under a different name: L<CPAN::Meta::Requirements>.
+
+=back
+
+=head1 Documentation
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perldata>
+
+=over 4
+
+=item *
+
+Now explicitly documents the behaviour of hash initializer lists that
+contain duplicate keys.
+
+=back
+
+=head3 L<perldiag>
+
+=over 4
+
+=item *
+
+The explanation of symbolic references being prevented by "strict refs"
+now doesn't assume that the reader knows what symbolic references are.
+
+=back
+
+=head3 L<perlfunc>
+
+=over 4
+
+=item *
+
+The return value of C<pipe> is now documented.
+
+=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<Unescaped left brace in regex is deprecated, passed
+through|perldiag/"Unescaped left brace in regex is deprecated, passed
+through">" is a new deprecation warning. See L</Unescaped braces in
+regexps>.
+
+=back
+
+=head1 Testing
+
+=over 4
+
+=item *
+
+The test suite now has a section for tests that require very large amounts
+of memory. These tests won't run by default; they can be enabled by
+setting the C<PERL_TEST_MEMORY> environment variable to the number of
+gibibytes of memory that may be safely used.
+
+=back
+
+=head1 Platform Support
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item clang++
+
+There is now a workaround for a compiler bug that prevented compiling
+with clang++ since Perl 5.15.7 [perl #112786].
+
+=item C++
+
+When compiling the Perl core as C++ (which is only semi-supported), the
+mathom functions are now compiled as C<extern "C">, to ensure proper
+binary compatibility. (However, binary compatibility isn't generally
+guaranteed anyway in the situations where this would matter.)
+
+=item VMS
+
+It should now be possible to compile Perl as C++ on VMS.
+
+=back
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+The C<CV *> typemap entry now supports C<&{}> overloading and typeglobs,
+just like C<&{...}> [perl #96872].
+
+=item *
+
+The C<SVf_AMAGIC> flag to indicate overloading is now on the stash, not the
+object. It is now set automatically whenever a method or @ISA changes, so
+its meaning has changed, too. It now means "potentially overloaded". When
+the overload table is calculated, the flag is automatically turned off if
+there is no overloading, so there should be no noticeable slowdown.
+
+The staleness of the overload tables is now checked when overload methods
+are invoked, rather than during C<bless>.
+
+"A" magic is gone. The changes to the handling of the C<SVf_AMAGIC> flag
+eliminate the need for it.
+
+C<PL_amagic_generation> has been removed as no longer necessary. For XS
+modules, it is now a macro alias to C<PL_na>.
+
+The fallback overload setting is now stored in a stash entry separate from
+overloadedness itself.
+
+=item *
+
+The character-processing code has been cleaned up in places. The changes
+should be operationally invisible.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+C<goto ''> now looks for an empty label, producing the "goto must have
+label" error message, instead of exiting the program [perl #111794].
+
+=item *
+
+C<goto "\0"> now dies with "Can't find label" instead of "goto must have
+label".
+
+=item *
+
+The C function C<hv_store> used to result in crashes when used on C<%^H>
+[perl #111000].
+
+=item *
+
+A call checker attached to a closure prototype via C<cv_set_call_checker>
+is now copied to closures cloned from it. So C<cv_set_call_checker> now
+works inside an attribute handler for a closure.
+
+=item *
+
+Writing to C<$^N> used to have no effect. Now it croaks with "Modification
+of a read-only value" by default, but that can be overridden by a custom
+regular expression engine, as with C<$1> [perl #112184].
+
+=item *
+
+C<undef> on a control character glob (C<undef *^H>) no longer emits an
+erroneous warning about ambiguity [perl #112456].
+
+=item *
+
+For efficiency's sake, many operators and built-in functions return the
+same scalar each time. Lvalue subroutines and subroutines in the CORE::
+namespace were allowing this implementation detail to leak through.
+C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB". The same thing
+would happen with an lvalue subroutine returning the return value of C<uc>.
+Now the value is copied in such cases.
+
+=item *
+
+C<method {}> syntax with an empty block or a block returning an empty list
+used to crash or use some random value left on the stack as its invocant.
+Now it produces an error.
+
+=item *
+
+C<vec> now works with extremely large offsets (E<gt>2 GB) [perl #111730].
+
+=item *
+
+Changes to overload settings now take effect immediately, as do changes to
+inheritance that affect overloading. They used to take effect only after
+C<bless>.
+
+Objects that were created before a class had any overloading used to remain
+non-overloaded even if the class gained overloading through C<use overload>
+or @ISA changes, and even after C<bless>. This has been fixed
+[perl #112708].
+
+=item *
+
+Classes with overloading can now inherit fallback values.
+
+=item *
+
+Overloading was not respecting a fallback value of 0 if there were
+overloaded objects on both sides of an assignment operator like C<+=>
+[perl #111856].
+
+=item *
+
+C<pos> now croaks with hash and array arguments, instead of producing
+erroneous warnings.
+
+=item *
+
+C<while(each %h)> now implies C<while(defined($_ = each %h))>, like
+C<readline> and C<readdir>.
+
+=item *
+
+Subs in the CORE:: namespace no longer crash after C<undef *_> when called
+with no argument list (C<&CORE::time> with no parentheses).
+
+=item *
+
+Unicode 6.1 published an incorrect alias for one of the
+Canonical_Combining_Class property's values (which range between 0 and
+254). The alias C<CCC133> should have been C<CCC132>. Perl now
+overrides the data file furnished by Unicode to give the correct value.
+
+=item *
+
+C<unpack> no longer produces the "'/' must follow a numeric type in unpack"
+error when it is the data that are at fault [perl #60204].
+
+=item *
+
+C<join> and C<"@array"> now call FETCH only once on a tied C<$">
+[perl #8931].
+
+=item *
+
+Some subroutine calls generated by compiling core ops affected by a
+C<CORE::GLOBAL> override had op checking performed twice. The checking
+is always idempotent for pure Perl code, but the double checking can
+matter when custom call checkers are involved.
+
+=item *
+
+A race condition used to exist around fork that could cause a signal sent to
+the parent to be handled by both parent and child. Signals are now blocked
+briefly around fork to prevent this from happening [perl #82580].
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.17.0 represents approximately 1 week of development since Perl 5.16.0
+and contains approximately 17,000 lines of changes across 180 files from 26
+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.16.1:
+
+Alan Haggai Alavi, Aristotle Pagaltzis, Brian Fraser, Chris 'BinGOs' Williams,
+Craig A. Berry, Dagfinn Ilmari Mannsåker, Eric Brine, Father Chrysostomos,
+Igor Zaytsev, James E Keenan, Karl Williamson, Leon Timmermans, Lukas Mai,
+Marcus Holland-Moritz, Matthew Horsfall, Moritz Lenz, Rafael Garcia-Suarez,
+Reini Urban, Ricardo Signes, Robin Barker, Ronald J. Kimball, Smylers, Steffen
+Müller, Steve Hay, Tony Cook, Zefram.
+
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the 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
=head1 NAME
-perldelta - what is new for perl v5.17.0
+[ this is a template for a new perldelta file. Any text flagged as
+XXX needs to be processed before release. ]
+
+perldelta - what is new for perl v5.17.1
=head1 DESCRIPTION
-This document describes differences between the 5.16.0 release and
-the 5.17.0 release.
+This document describes differences between the 5.17.0 release and
+the 5.17.1 release.
If you are upgrading from an earlier release such as 5.16.0, first read
-L<perl5160delta>, which describes differences between 5.14.0 and
-5.16.0.
+L<perl5170delta>, which describes differences between 5.16.0 and
+5.17.0.
-=head1 Incompatible Changes
+=head1 Notice
-=head2 qw(...) can no longer be used as parentheses
+XXX Any important notices here
-C<qw> lists used to fool the parser into thinking they were always
-surrounded by parentheses. This permitted some surprising constructions
-such as C<foreach $x qw(a b c) {...}>, which should really be written
-C<foreach $x (qw(a b c)) {...}>. These would sometimes get the lexer into
-the wrong state, so they didn't fully work, and the similar C<foreach qw(a
-b c) {...}> that one might expect to be permitted never worked at all.
+=head1 Core Enhancements
-This side effect of C<qw> has now been abolished. It has been deprecated
-since Perl 5.13.11. It is now necessary to use real parentheses
-everywhere that the grammar calls for them.
+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.
-=head2 C<\s> in regular expressions now matches a Vertical Tab (experimental)
+[ List each enhancement as a =head2 entry ]
-This is an experiment early in the development cycle to see what
-repercussions arise from this change. It may well be that we decide
-to require a C<"use feature"> to activate this behavior. Because
-of the experimental nature of this, which may be reversed, the
-documentation has not been changed to reflect it.
+=head1 Security
-=head1 Deprecations
+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 Unescaped braces in regexps
+[ List each security issue as a =head2 entry ]
-Literal unescaped C<{> in regular expressions is now deprecated. Every
-brace character should be either escaped (by a preceding backslash) or
-part of a construct where it's a metacharacter. This catches likely typos
-such as C</f{,3}/>. It will also allow braces to be used in the future
-to delimit parameters to metacharacters that currently take no parameters.
+=head1 Incompatible Changes
-=head1 Performance Enhancements
+XXX For a release on a stable branch, this section aspires to be:
-=over 4
+ 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.
-=item *
+[ List each incompatible change as a =head2 entry ]
-Filetest ops manage the stack in a fractionally more efficient manner.
+=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.
-Globs used in a numeric context are now numerified directly in most cases,
-rather than being numerified via stringification.
+[ List each deprecation as a =head2 entry ]
-=back
+=head1 Performance Enhancements
-=head1 Modules and Pragmata
+XXX Changes which enhance performance without changing behaviour go here. There
+may well be none in a stable release.
-=head2 Updated Modules and Pragmata
+[ List each enhancement as a =item entry ]
=over 4
=item *
-L<B> has been upgraded from version 1.34 to 1.35.
-
-The C<stashlen> method of COPs has been added. This provides access to an
-internal field added in perl 5.16 under threaded builds [perl #113034].
-
-=item *
+XXX
-L<ExtUtils::ParseXS> has been upgraded from version 3.16 to 3.17.
-
-The generated C code now avoids unnecessarily incrementing
-C<PL_amagic_generation> on Perl versions where it's done automatically
-(or on current Perl where the variable no longer exists).
-
-=item *
-
-L<File::DosGlob> has been upgraded from version 1.06 to 1.07.
-
-Small documentation and comment fixes.
-
-=item *
-
-L<File::Find> has been upgraded from version 1.20 to 1.21.
+=back
-Individual files may now appear in list of directories to be searched
-[perl #59750].
+=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.
-L<File::stat> has been upgraded from version 1.05 to 1.06.
+[ Within each section, list entries as a =item entry ]
-C<File::stat> ignores the L<filetest> pragma, and warns when used in
-combination therewith. But it was not warning for C<-r>. This has been
-fixed [perl #111640].
+=head2 New Modules and Pragmata
-C<-p> now works, and does not return false for pipes [perl #111638].
+=over 4
=item *
-L<Hash::Util> has been upgraded from version 0.11 to 0.12.
+XXX
-C<hash_unlocked> and C<hashref_unlocked> now returns true if the hash is
-unlocked, instead of always returning false [perl #112126].
+=back
-C<hash_unlocked>, C<hashref_unlocked>, C<lock_hash_recurse> and
-C<unlock_hash_recurse> are now exportable [perl #112126].
+=head2 Updated Modules and Pragmata
-Two new functions, C<hash_locked> and C<hashref_locked>, have been added.
-Oddly enough, these two functions were already exported, even though they
-did not exist [perl #112126].
+=over 4
=item *
-L<Module::CoreList> has been upgraded from version 2.66 to 2.67.
+L<XXX> has been upgraded from version 0.69 to version 0.70.
-=item *
+=back
-L<overload> has been upgraded from version 1.18 to 1.19.
+=head2 Removed Modules and Pragmata
-C<no overload> now warns for invalid arguments, just like C<use overload>.
+=over 4
=item *
-L<Pod::Functions> has been upgraded from version 1.05 to 1.06.
+XXX
-Typo fix in generated documentation.
+=back
-=item *
+=head1 Documentation
-L<Storable> has been upgraded from version 2.34 to 2.35.
+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>.
-Modifying C<$_[0]> within C<STORABLE_freeze> no longer results in crashes
-[perl #112358].
+=head2 New Documentation
-An object whose class implements C<STORABLE_attach> is now thawed only once
-when there are multiple references to it in the structure being thawed
-[perl #111918].
+XXX Changes which create B<new> files in F<pod/> go here.
-=item *
+=head3 L<XXX>
-L<utf8> has been upgraded from version 1.09 to 1.10.
+XXX Description of the purpose of the new file here
-Some documentation has been clarified.
+=head2 Changes to Existing Documentation
-=back
+XXX Changes which significantly change existing files in F<pod/> go here.
+However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
+section.
-=head2 Removed Modules and Pragmata
+=head3 L<XXX>
=over 4
=item *
-L<Version::Requirements> has been removed from the core distribution. It is
-available under a different name: L<CPAN::Meta::Requirements>.
+XXX Description of the change here
=back
-=head1 Documentation
-
-=head2 Changes to Existing Documentation
-
-=head3 L<perldata>
+=head1 Diagnostics
-=over 4
+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>.
-=item *
+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.
-Now explicitly documents the behaviour of hash initializer lists that
-contain duplicate keys.
+[ Within each section, list entries as a =item entry that links to perldiag,
+ e.g.
-=back
+ =item *
-=head3 L<perldiag>
+ L<Invalid version object|perldiag/"Invalid version object">
+]
-=over 4
-
-=item *
+=head2 New Diagnostics
-The explanation of symbolic references being prevented by "strict refs"
-now doesn't assume that the reader knows what symbolic references are.
+XXX Newly added diagnostic messages go here
-=back
-
-=head3 L<perlfunc>
+=head3 New Errors
=over 4
=item *
-The return value of C<pipe> is now documented.
+XXX L<message|perldiag/"message">
=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<Unescaped left brace in regex is deprecated, passed
-through|perldiag/"Unescaped left brace in regex is deprecated, passed
-through">" is a new deprecation warning. See L</Unescaped braces in
-regexps>.
+XXX L<message|perldiag/"message">
=back
-=head1 Testing
+=head2 Changes to Existing Diagnostics
+
+XXX Changes (i.e. rewording) of diagnostic messages go here
=over 4
=item *
-The test suite now has a section for tests that require very large amounts
-of memory. These tests won't run by default; they can be enabled by
-setting the C<PERL_TEST_MEMORY> environment variable to the number of
-gibibytes of memory that may be safely used.
+XXX Describe change here
=back
-=head1 Platform Support
+=head1 Utility Changes
-=head2 Platform-Specific Notes
+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>.
-=over 4
+[ 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. ]
-=item clang++
+=head3 L<XXX>
-There is now a workaround for a compiler bug that prevented compiling
-with clang++ since Perl 5.15.7 [perl #112786].
+=over 4
-=item C++
+=item *
-When compiling the Perl core as C++ (which is only semi-supported), the
-mathom functions are now compiled as C<extern "C">, to ensure proper
-binary compatibility. (However, binary compatibility isn't generally
-guaranteed anyway in the situations where this would matter.)
+XXX
-=item VMS
+=back
-It should now be possible to compile Perl as C++ on VMS.
+=head1 Configuration and Compilation
-=back
+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.
-=head1 Internal Changes
+[ List changes as a =item entry ].
=over 4
=item *
-The C<CV *> typemap entry now supports C<&{}> overloading and typeglobs,
-just like C<&{...}> [perl #96872].
-
-=item *
+XXX
-The C<SVf_AMAGIC> flag to indicate overloading is now on the stash, not the
-object. It is now set automatically whenever a method or @ISA changes, so
-its meaning has changed, too. It now means "potentially overloaded". When
-the overload table is calculated, the flag is automatically turned off if
-there is no overloading, so there should be no noticeable slowdown.
+=back
-The staleness of the overload tables is now checked when overload methods
-are invoked, rather than during C<bless>.
+=head1 Testing
-"A" magic is gone. The changes to the handling of the C<SVf_AMAGIC> flag
-eliminate the need for it.
+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.
-C<PL_amagic_generation> has been removed as no longer necessary. For XS
-modules, it is now a macro alias to C<PL_na>.
+[ List each test improvement as a =item entry ]
-The fallback overload setting is now stored in a stash entry separate from
-overloadedness itself.
+=over 4
=item *
-The character-processing code has been cleaned up in places. The changes
-should be operationally invisible.
+XXX
=back
-=head1 Selected Bug Fixes
+=head1 Platform Support
-=over 4
+XXX Any changes to platform support should be listed in the sections below.
-=item *
+[ Within the sections, list each platform as a =item entry with specific
+changes as paragraphs below it. ]
-C<goto ''> now looks for an empty label, producing the "goto must have
-label" error message, instead of exiting the program [perl #111794].
+=head2 New Platforms
-=item *
+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.
-C<goto "\0"> now dies with "Can't find label" instead of "goto must have
-label".
+=over 4
-=item *
+=item XXX-some-platform
-The C function C<hv_store> used to result in crashes when used on C<%^H>
-[perl #111000].
+XXX
-=item *
+=back
-A call checker attached to a closure prototype via C<cv_set_call_checker>
-is now copied to closures cloned from it. So C<cv_set_call_checker> now
-works inside an attribute handler for a closure.
+=head2 Discontinued Platforms
-=item *
+XXX List any platforms that this version of perl no longer compiles on.
-Writing to C<$^N> used to have no effect. Now it croaks with "Modification
-of a read-only value" by default, but that can be overridden by a custom
-regular expression engine, as with C<$1> [perl #112184].
+=over 4
-=item *
+=item XXX-some-platform
-C<undef> on a control character glob (C<undef *^H>) no longer emits an
-erroneous warning about ambiguity [perl #112456].
+XXX
-=item *
+=back
-For efficiency's sake, many operators and built-in functions return the
-same scalar each time. Lvalue subroutines and subroutines in the CORE::
-namespace were allowing this implementation detail to leak through.
-C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB". The same thing
-would happen with an lvalue subroutine returning the return value of C<uc>.
-Now the value is copied in such cases.
+=head2 Platform-Specific Notes
-=item *
+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.
-C<method {}> syntax with an empty block or a block returning an empty list
-used to crash or use some random value left on the stack as its invocant.
-Now it produces an error.
+=over 4
-=item *
+=item XXX-some-platform
-C<vec> now works with extremely large offsets (E<gt>2 GB) [perl #111730].
+XXX
-=item *
+=back
-Changes to overload settings now take effect immediately, as do changes to
-inheritance that affect overloading. They used to take effect only after
-C<bless>.
+=head1 Internal Changes
-Objects that were created before a class had any overloading used to remain
-non-overloaded even if the class gained overloading through C<use overload>
-or @ISA changes, and even after C<bless>. This has been fixed
-[perl #112708].
+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 ]
-Classes with overloading can now inherit fallback values.
+=over 4
=item *
-Overloading was not respecting a fallback value of 0 if there were
-overloaded objects on both sides of an assignment operator like C<+=>
-[perl #111856].
-
-=item *
+XXX
-C<pos> now croaks with hash and array arguments, instead of producing
-erroneous warnings.
+=back
-=item *
+=head1 Selected Bug Fixes
-C<while(each %h)> now implies C<while(defined($_ = each %h))>, like
-C<readline> and C<readdir>.
+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>.
-=item *
+[ List each fix as a =item entry ]
-Subs in the CORE:: namespace no longer crash after C<undef *_> when called
-with no argument list (C<&CORE::time> with no parentheses).
+=over 4
=item *
-Unicode 6.1 published an incorrect alias for one of the
-Canonical_Combining_Class property's values (which range between 0 and
-254). The alias C<CCC133> should have been C<CCC132>. Perl now
-overrides the data file furnished by Unicode to give the correct value.
+XXX
-=item *
+=back
-C<unpack> no longer produces the "'/' must follow a numeric type in unpack"
-error when it is the data that are at fault [perl #60204].
+=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<join> and C<"@array"> now call FETCH only once on a tied C<$">
-[perl #8931].
+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 ]
-Some subroutine calls generated by compiling core ops affected by a
-C<CORE::GLOBAL> override had op checking performed twice. The checking
-is always idempotent for pure Perl code, but the double checking can
-matter when custom call checkers are involved.
+=over 4
=item *
-A race condition used to exist around fork that could cause a signal sent to
-the parent to be handled by both parent and child. Signals are now blocked
-briefly around fork to prevent this from happening [perl #82580].
+XXX
=back
-=head1 Acknowledgements
+=head1 Obituary
-Perl 5.17.0 represents approximately 1 week of development since Perl 5.16.0
-and contains approximately 17,000 lines of changes across 180 files from 26
-authors.
+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.16.1:
-
-Alan Haggai Alavi, Aristotle Pagaltzis, Brian Fraser, Chris 'BinGOs' Williams,
-Craig A. Berry, Dagfinn Ilmari Mannsåker, Eric Brine, Father Chrysostomos,
-Igor Zaytsev, James E Keenan, Karl Williamson, Leon Timmermans, Lukas Mai,
-Marcus Holland-Moritz, Matthew Horsfall, Moritz Lenz, Rafael Garcia-Suarez,
-Reini Urban, Ricardo Signes, Robin Barker, Ronald J. Kimball, Smylers, Steffen
-Müller, Steve Hay, Tony Cook, Zefram.
-
-The list above is almost certainly incomplete as it is automatically generated
-from version control history. In particular, it does not include the names of
-the (very much appreciated) contributors who reported issues to the Perl bug
-tracker.
+=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.17.0..HEAD
=head1 Reporting Bugs