This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for the 79881ad71252 merge
[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 XXX needs
6 to be processed before release. ]
7
8 perldelta - what is new for perl v5.25.2
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.25.1 release and the 5.25.2
13 release.
14
15 If you are upgrading from an earlier release such as 5.25.0, first read
16 L<perl5251delta>, which describes differences between 5.25.0 and 5.25.1.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 [ List each enhancement as a =head2 entry ]
29
30 =head2 Perl can now do default collation in UTF-8 locales on platforms
31 that support it
32
33 Some platforms natively do a reasonable job of collating and sorting in
34 UTF-8 locales.  Perl now works with those.  For portability and full
35 control, L<Unicode::Collate> is still recommended, but now you may
36 not need to do anything special to get good-enough results, depending on
37 your application.  See
38 L<perllocale/Category C<LC_COLLATE>: Collation: Text Comparisons and Sorting>
39
40 =head2 Better locale collation of strings containing embedded C<NUL>
41 characters
42
43 In locales that have multi-level character weights, these are now
44 ignored at the higher priority ones.  There are still some gotchas in
45 some strings, though.  See
46 L<perllocale/Collation of strings containing embedded C<NUL> characters>.
47
48 =head1 Security
49
50 XXX Any security-related notices go here.  In particular, any security
51 vulnerabilities closed should be noted here rather than in the
52 L</Selected Bug Fixes> section.
53
54 [ List each security issue as a =head2 entry ]
55
56 =head2 C<-Di> switch is now required for PerlIO debugging output
57
58 Previously PerlIO debugging output would be sent to the file specified
59 by the C<PERLIO_DEBUG> environment variable if perl wasn't running
60 setuid and the C<-T> or C<-t> switches hadn't been parsed yet.
61
62 If perl performed output at a point where it hadn't yet parsed its
63 switches this could result in perl creating or overwriting the file
64 named by C<PERLIO_DEBUG> even when the C<-T> switch had been supplied.
65
66 Perl now requires the C<-Di> switch to produce PerlIO debugging
67 output.  By default this is written to C<stderr>, but can optionally
68 be redirected to a file by setting the C<PERLIO_DEBUG> environment
69 variable.
70
71 If perl is running setuid or the C<-T> switch has supplied
72 C<PERLIO_DEBUG> is ignored and the debugging output is sent to
73 C<stderr> as for any other C<-D> switch.
74
75 =head1 Incompatible Changes
76
77 XXX For a release on a stable branch, this section aspires to be:
78
79     There are no changes intentionally incompatible with 5.XXX.XXX
80     If any exist, they are bugs, and we request that you submit a
81     report.  See L</Reporting Bugs> below.
82
83 [ List each incompatible change as a =head2 entry ]
84
85 =head1 Deprecations
86
87 XXX Any deprecated features, syntax, modules etc. should be listed here.
88
89 =head2 Module removals
90
91 XXX Remove this section if inapplicable.
92
93 The following modules will be removed from the core distribution in a
94 future release, and will at that time need to be installed from CPAN.
95 Distributions on CPAN which require these modules will need to list them as
96 prerequisites.
97
98 The core versions of these modules will now issue C<"deprecated">-category
99 warnings to alert you to this fact.  To silence these deprecation warnings,
100 install the modules in question from CPAN.
101
102 Note that these are (with rare exceptions) fine modules that you are encouraged
103 to continue to use.  Their disinclusion from core primarily hinges on their
104 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
105 not usually on concerns over their design.
106
107 =over
108
109 =item XXX
110
111 XXX Note that deprecated modules should be listed here even if they are listed
112 as an updated module in the L</Modules and Pragmata> section.
113
114 =back
115
116 [ List each other deprecation as a =head2 entry ]
117
118 =head1 Performance Enhancements
119
120 XXX Changes which enhance performance without changing behaviour go here.
121 There may well be none in a stable release.
122
123 [ List each enhancement as a =item entry ]
124
125 =over 4
126
127 =item *
128
129 XXX
130
131 =back
132
133 =head1 Modules and Pragmata
134
135 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
136 go here.  If Module::CoreList is updated, generate an initial draft of the
137 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
138 for important changes should then be added by hand.  In an ideal world,
139 dual-life modules would have a F<Changes> file that could be cribbed.
140
141 [ Within each section, list entries as a =item entry ]
142
143 =head2 New Modules and Pragmata
144
145 =over 4
146
147 =item *
148
149 XXX
150
151 =back
152
153 =head2 Updated Modules and Pragmata
154
155 =over 4
156
157 =item *
158
159 L<XXX> has been upgraded from version A.xx to B.yy.
160
161 =item *
162
163 L<Module::CoreList> has been upgraded from 5.20160520 to 5.20160620.
164
165 =back
166
167 =head2 Removed Modules and Pragmata
168
169 =over 4
170
171 =item *
172
173 XXX
174
175 =back
176
177 =head1 Documentation
178
179 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
180 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
181
182 =head2 New Documentation
183
184 XXX Changes which create B<new> files in F<pod/> go here.
185
186 =head3 L<XXX>
187
188 XXX Description of the purpose of the new file here
189
190 =head2 Changes to Existing Documentation
191
192 XXX Changes which significantly change existing files in F<pod/> go here.
193 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
194 section.
195
196 =head3 L<XXX>
197
198 =over 4
199
200 =item *
201
202 XXX Description of the change here
203
204 =back
205
206 =head1 Diagnostics
207
208 The following additions or changes have been made to diagnostic output,
209 including warnings and fatal error messages.  For the complete list of
210 diagnostic messages, see L<perldiag>.
211
212 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
213 include any changes in L<perldiag> that reconcile it to the C<C> code.
214
215 =head2 New Diagnostics
216
217 XXX Newly added diagnostic messages go under here, separated into New Errors
218 and New Warnings
219
220 =head3 New Errors
221
222 =over 4
223
224 =item *
225
226 L<Version control conflict marker|perldiag/"Version control conflict marker">
227
228 =item *
229
230 XXX L<message|perldiag/"message">
231
232 =back
233
234 =head3 New Warnings
235
236 =over 4
237
238 =item *
239
240 XXX L<message|perldiag/"message">
241
242 =back
243
244 =head2 Changes to Existing Diagnostics
245
246 XXX Changes (i.e. rewording) of diagnostic messages go here
247
248 =over 4
249
250 =item *
251
252 XXX Describe change here
253
254 =back
255
256 =head1 Utility Changes
257
258 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
259 Most of these are built within the directory F<utils>.
260
261 [ List utility changes as a =head2 entry for each utility and =item
262 entries for each change
263 Use L<XXX> with program names to get proper documentation linking. ]
264
265 =head2 L<XXX>
266
267 =over 4
268
269 =item *
270
271 XXX
272
273 =back
274
275 =head1 Configuration and Compilation
276
277 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
278 go here.  Any other changes to the Perl build process should be listed here.
279 However, any platform-specific changes should be listed in the
280 L</Platform Support> section, instead.
281
282 [ List changes as a =item entry ].
283
284 =over 4
285
286 =item *
287
288 XXX
289
290 =back
291
292 =head1 Testing
293
294 XXX Any significant changes to the testing of a freshly built perl should be
295 listed here.  Changes which create B<new> files in F<t/> go here as do any
296 large changes to the testing harness (e.g. when parallel testing was added).
297 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
298 that they represent may be covered elsewhere.
299
300 [ List each test improvement as a =item entry ]
301
302 =over 4
303
304 =item *
305
306 XXX
307
308 =back
309
310 =head1 Platform Support
311
312 XXX Any changes to platform support should be listed in the sections below.
313
314 [ Within the sections, list each platform as a =item entry with specific
315 changes as paragraphs below it. ]
316
317 =head2 New Platforms
318
319 XXX List any platforms that this version of perl compiles on, that previous
320 versions did not.  These will either be enabled by new files in the F<hints/>
321 directories, or new subdirectories and F<README> files at the top level of the
322 source tree.
323
324 =over 4
325
326 =item XXX-some-platform
327
328 XXX
329
330 =back
331
332 =head2 Discontinued Platforms
333
334 XXX List any platforms that this version of perl no longer compiles on.
335
336 =over 4
337
338 =item XXX-some-platform
339
340 XXX
341
342 =back
343
344 =head2 Platform-Specific Notes
345
346 XXX List any changes for specific platforms.  This could include configuration
347 and compilation changes or changes in portability/compatibility.  However,
348 changes within modules for platforms should generally be listed in the
349 L</Modules and Pragmata> section.
350
351 =over 4
352
353 =item XXX-some-platform
354
355 XXX
356
357 =back
358
359 =head1 Internal Changes
360
361 XXX Changes which affect the interface available to C<XS> code go here.  Other
362 significant internal changes for future core maintainers should be noted as
363 well.
364
365 [ List each change as a =item entry ]
366
367 =over 4
368
369 =item *
370
371 Perl no longer panics when switching into some locales on machines with
372 buggy C<strxfrm()> implementations in their libc. [perl #121734]
373
374 =back
375
376 =head1 Selected Bug Fixes
377
378 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
379 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
380
381 [ List each fix as a =item entry ]
382
383 =over 4
384
385 =item *
386
387 C< until ($x = 1) { ... } > and C< ... until $x = 1 > now properly
388 warn when syntax warnings are enabled.  [perl #127333]
389
390 =back
391
392 =head1 Known Problems
393
394 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
395 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
396 platform specific bugs also go here.
397
398 [ List each fix as a =item entry ]
399
400 =over 4
401
402 =item *
403
404 XXX
405
406 =back
407
408 =head1 Errata From Previous Releases
409
410 =over 4
411
412 =item *
413
414 XXX Add anything here that we forgot to add, or were mistaken about, in
415 the perldelta of a previous release.
416
417 =back
418
419 =head1 Obituary
420
421 XXX If any significant core contributor has died, we've added a short obituary
422 here.
423
424 =head1 Acknowledgements
425
426 XXX Generate this with:
427
428   perl Porting/acknowledgements.pl v5.25.1..HEAD
429
430 =head1 Reporting Bugs
431
432 If you find what you think is a bug, you might check the articles recently
433 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
434 L<https://rt.perl.org/> .  There may also be information at
435 L<http://www.perl.org/> , the Perl Home Page.
436
437 If you believe you have an unreported bug, please run the L<perlbug> program
438 included with your release.  Be sure to trim your bug down to a tiny but
439 sufficient test case.  Your bug report, along with the output of C<perl -V>,
440 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
441
442 If the bug you are reporting has security implications which make it
443 inappropriate to send to a publicly archived mailing list, then see
444 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
445 for details of how to report the issue.
446
447 =head1 SEE ALSO
448
449 The F<Changes> file for an explanation of how to view exhaustive details on
450 what changed.
451
452 The F<INSTALL> file for how to build Perl.
453
454 The F<README> file for general stuff.
455
456 The F<Artistic> and F<Copying> files for copyright information.
457
458 =cut