This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 2ba1f20ac3a (loopex prec docs)
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 [ this is a template for a new perldelta file. Any text flagged as
6 XXX needs to be processed before release. ]
7
8 perldelta - what is new for perl v5.17.3
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.17.2 release and
13 the 5.17.3 release.
14
15 If you are upgrading from an earlier release such as 5.17.1, first read
16 L<perl5172delta>, which describes differences between 5.17.1 and
17 5.17.2.
18
19 =head1 Notice
20
21 XXX Any important notices here
22
23 =head1 Core Enhancements
24
25 XXX New core language features go here. Summarise user-visible core language
26 enhancements. Particularly prominent performance optimisations could go
27 here, but most should go in the L</Performance Enhancements> section.
28
29 [ List each enhancement as a =head2 entry ]
30
31 =head1 Security
32
33 XXX Any security-related notices go here.  In particular, any security
34 vulnerabilities closed should be noted here rather than in the
35 L</Selected Bug Fixes> section.
36
37 [ List each security issue as a =head2 entry ]
38
39 =head1 Incompatible Changes
40
41 [ List each incompatible change as a =head2 entry ]
42
43 =head2 C<$ENV{foo} = undef> deletes value from environ, like C<delete $ENV{foo}>
44
45 This facilitates use of C<local()> with C<%ENV> entries.  In previous
46 versions of Perl, C<undef> was converted to the empty string.
47
48 =head2 Defined values stored in environment are forced to byte strings
49
50 A value stored in an environment variable has always been stringified.  In
51 this release, it is converted to be only a byte string.  First, it is forced
52 to be a only a string.  Then if the string is utf8 and the equivalent of
53 C<utf8::downgrade> works, that result is used; otherwise, the equivalent of
54 C<utf8::encode> is used, and a warning is issued about wide characters
55 (L</Diagnostics>).
56
57 =head1 Deprecations
58
59 XXX Any deprecated features, syntax, modules etc. should be listed here.
60 In particular, deprecated modules should be listed here even if they are
61 listed as an updated module in the L</Modules and Pragmata> section.
62
63 [ List each deprecation as a =head2 entry ]
64
65 =head1 Performance Enhancements
66
67 XXX Changes which enhance performance without changing behaviour go here. There
68 may well be none in a stable release.
69
70 [ List each enhancement as a =item entry ]
71
72 =over 4
73
74 =item *
75
76 XXX
77
78 =back
79
80 =head1 Modules and Pragmata
81
82 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
83 go here.  If Module::CoreList is updated, generate an initial draft of the
84 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
85 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
86 below.  A paragraph summary for important changes should then be added by hand.
87 In an ideal world, dual-life modules would have a F<Changes> file that could be
88 cribbed.
89
90 [ Within each section, list entries as a =item entry ]
91
92 =head2 New Modules and Pragmata
93
94 =over 4
95
96 =item *
97
98 XXX
99
100 =back
101
102 =head2 Updated Modules and Pragmata
103
104 =over 4
105
106 =item *
107
108 L<B> has been upgraded from version 1.36 to version 1.37. All C<CVf_*> and
109 C<GVf_*> and more SV-related flag values are now provided as constants in
110 the C<B::> namespace and available for export. The default export list has
111 not changed.
112
113 =back
114
115 =head2 Removed Modules and Pragmata
116
117 =over 4
118
119 =item *
120
121 XXX
122
123 =back
124
125 =head1 Documentation
126
127 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
128 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
129
130 =head2 New Documentation
131
132 XXX Changes which create B<new> files in F<pod/> go here.
133
134 =head3 L<XXX>
135
136 XXX Description of the purpose of the new file here
137
138 =head2 Changes to Existing Documentation
139
140 XXX Changes which significantly change existing files in F<pod/> go here.
141 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
142 section.
143
144 =head3 L<perlfunc>, L<perlop>
145
146 =over 4
147
148 =item *
149
150 Loop control verbs (C<dump>, C<goto>, C<next>, C<last> and C<redo>) have
151 always had the same precedence as assignment operators, but this was never
152 documented until now.
153
154 =back
155
156 =head1 Diagnostics
157
158 The following additions or changes have been made to diagnostic output,
159 including warnings and fatal error messages.  For the complete list of
160 diagnostic messages, see L<perldiag>.
161
162 XXX New or changed warnings emitted by the core's C<C> code go here. Also
163 include any changes in L<perldiag> that reconcile it to the C<C> code.
164
165 [ Within each section, list entries as a =item entry that links to perldiag,
166   e.g.
167
168   =item *
169
170   L<Invalid version object|perldiag/"Invalid version object">
171 ]
172
173 =head2 New Diagnostics
174
175 XXX Newly added diagnostic messages go here
176
177 =over 4
178
179 =item *
180
181 Attempts to put wide characters into environment variables via %ENV provoke
182 the warning "Wide character in setenv".
183
184 =back
185
186 =head3 New Errors
187
188 =over 4
189
190 =item *
191
192 XXX L<message|perldiag/"message">
193
194 =back
195
196 =head3 New Warnings
197
198 =over 4
199
200 =item *
201
202 XXX L<message|perldiag/"message">
203
204 =back
205
206 =head2 Changes to Existing Diagnostics
207
208 XXX Changes (i.e. rewording) of diagnostic messages go here
209
210 =over 4
211
212 =item *
213
214 XXX Describe change here
215
216 =back
217
218 =head1 Utility Changes
219
220 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
221 here. Most of these are built within the directories F<utils> and F<x2p>.
222
223 [ List utility changes as a =head3 entry for each utility and =item
224 entries for each change
225 Use L<XXX> with program names to get proper documentation linking. ]
226
227 =head3 L<XXX>
228
229 =over 4
230
231 =item *
232
233 XXX
234
235 =back
236
237 =head1 Configuration and Compilation
238
239 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
240 go here.  Any other changes to the Perl build process should be listed here.
241 However, any platform-specific changes should be listed in the
242 L</Platform Support> section, instead.
243
244 [ List changes as a =item entry ].
245
246 =over 4
247
248 =item *
249
250 XXX
251
252 =back
253
254 =head1 Testing
255
256 XXX Any significant changes to the testing of a freshly built perl should be
257 listed here.  Changes which create B<new> files in F<t/> go here as do any
258 large changes to the testing harness (e.g. when parallel testing was added).
259 Changes to existing files in F<t/> aren't worth summarising, although the bugs
260 that they represent may be covered elsewhere.
261
262 [ List each test improvement as a =item entry ]
263
264 =over 4
265
266 =item *
267
268 XXX
269
270 =back
271
272 =head1 Platform Support
273
274 XXX Any changes to platform support should be listed in the sections below.
275
276 [ Within the sections, list each platform as a =item entry with specific
277 changes as paragraphs below it. ]
278
279 =head2 New Platforms
280
281 XXX List any platforms that this version of perl compiles on, that previous
282 versions did not. These will either be enabled by new files in the F<hints/>
283 directories, or new subdirectories and F<README> files at the top level of the
284 source tree.
285
286 =over 4
287
288 =item XXX-some-platform
289
290 XXX
291
292 =back
293
294 =head2 Discontinued Platforms
295
296 XXX List any platforms that this version of perl no longer compiles on.
297
298 =over 4
299
300 =item XXX-some-platform
301
302 XXX
303
304 =back
305
306 =head2 Platform-Specific Notes
307
308 XXX List any changes for specific platforms. This could include configuration
309 and compilation changes or changes in portability/compatibility.  However,
310 changes within modules for platforms should generally be listed in the
311 L</Modules and Pragmata> section.
312
313 =over 4
314
315 =item XXX-some-platform
316
317 XXX
318
319 =back
320
321 =head1 Internal Changes
322
323 XXX Changes which affect the interface available to C<XS> code go here.
324 Other significant internal changes for future core maintainers should
325 be noted as well.
326
327 [ List each change as a =item entry ]
328
329 =over 4
330
331 =item *
332
333 XXX
334
335 =back
336
337 =head1 Selected Bug Fixes
338
339 XXX Important bug fixes in the core language are summarised here.
340 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
341 L</Modules and Pragmata>.
342
343 [ List each fix as a =item entry ]
344
345 =over 4
346
347 =item *
348
349 C<\w> now matches the code points U+200C (ZERO WIDTH NON-JOINER) and
350 U+200D (ZERO WIDTH JOINER).  C<\W> no longer matches these.  This change
351 is because Unicode corrected their definition of what C<\w> should match.
352
353 =item *
354
355 C<dump LABEL> no longer leaks its label.
356
357 =item *
358
359 Constant folding no longer changes the behaviour of functions like C<stat>
360 and C<truncate> that can take either filenames or handles.
361 C<stat 1 ? foo : bar> nows treats its argument as a file name (since it is
362 an arbitrary expression), rather than the handle "foo".
363
364 =item *
365
366 C<truncate FOO, $len> no longer falls back to treating "FOO" as a file name
367 if the filehandle has been deleted.  This was broken in Perl 5.16.0.
368
369 =item *
370
371 Subroutine redefinitions after sub-to-glob and glob-to-glob assignments no
372 longer cause double frees or panic messages.
373
374 =back
375
376 =head1 Known Problems
377
378 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
379 tests that had to be C<TODO>ed for the release would be noted here. Unfixed
380 platform specific bugs also go here.
381
382 [ List each fix as a =item entry ]
383
384 =over 4
385
386 =item *
387
388 XXX
389
390 =back
391
392 =head1 Obituary
393
394 XXX If any significant core contributor has died, we've added a short obituary
395 here.
396
397 =head1 Acknowledgements
398
399 XXX Generate this with:
400
401   perl Porting/acknowledgements.pl v5.17.2..HEAD
402
403 =head1 Reporting Bugs
404
405 If you find what you think is a bug, you might check the articles
406 recently posted to the comp.lang.perl.misc newsgroup and the perl
407 bug database at http://rt.perl.org/perlbug/ .  There may also be
408 information at http://www.perl.org/ , the Perl Home Page.
409
410 If you believe you have an unreported bug, please run the L<perlbug>
411 program included with your release.  Be sure to trim your bug down
412 to a tiny but sufficient test case.  Your bug report, along with the
413 output of C<perl -V>, will be sent off to perlbug@perl.org to be
414 analysed by the Perl porting team.
415
416 If the bug you are reporting has security implications, which make it
417 inappropriate to send to a publicly archived mailing list, then please send
418 it to perl5-security-report@perl.org. This points to a closed subscription
419 unarchived mailing list, which includes
420 all the core committers, who will be able
421 to help assess the impact of issues, figure out a resolution, and help
422 co-ordinate the release of patches to mitigate or fix the problem across all
423 platforms on which Perl is supported. Please only use this address for
424 security issues in the Perl core, not for modules independently
425 distributed on CPAN.
426
427 =head1 SEE ALSO
428
429 The F<Changes> file for an explanation of how to view exhaustive details
430 on what changed.
431
432 The F<INSTALL> file for how to build Perl.
433
434 The F<README> file for general stuff.
435
436 The F<Artistic> and F<Copying> files for copyright information.
437
438 =cut