This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 31b6f23ed55c
[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 F<make_ext.pl> no longer updates a module's F<pm_to_blib> file when no
289 files require updates.  This could cause dependencies, F<perlmain.c>
290 in particular, to be rebuilt unnecessarily.  [perl #126710]
291
292 =back
293
294 =head1 Testing
295
296 XXX Any significant changes to the testing of a freshly built perl should be
297 listed here.  Changes which create B<new> files in F<t/> go here as do any
298 large changes to the testing harness (e.g. when parallel testing was added).
299 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
300 that they represent may be covered elsewhere.
301
302 [ List each test improvement as a =item entry ]
303
304 =over 4
305
306 =item *
307
308 XXX
309
310 =back
311
312 =head1 Platform Support
313
314 XXX Any changes to platform support should be listed in the sections below.
315
316 [ Within the sections, list each platform as a =item entry with specific
317 changes as paragraphs below it. ]
318
319 =head2 New Platforms
320
321 XXX List any platforms that this version of perl compiles on, that previous
322 versions did not.  These will either be enabled by new files in the F<hints/>
323 directories, or new subdirectories and F<README> files at the top level of the
324 source tree.
325
326 =over 4
327
328 =item XXX-some-platform
329
330 XXX
331
332 =back
333
334 =head2 Discontinued Platforms
335
336 XXX List any platforms that this version of perl no longer compiles on.
337
338 =over 4
339
340 =item XXX-some-platform
341
342 XXX
343
344 =back
345
346 =head2 Platform-Specific Notes
347
348 XXX List any changes for specific platforms.  This could include configuration
349 and compilation changes or changes in portability/compatibility.  However,
350 changes within modules for platforms should generally be listed in the
351 L</Modules and Pragmata> section.
352
353 =over 4
354
355 =item XXX-some-platform
356
357 XXX
358
359 =back
360
361 =head1 Internal Changes
362
363 XXX Changes which affect the interface available to C<XS> code go here.  Other
364 significant internal changes for future core maintainers should be noted as
365 well.
366
367 [ List each change as a =item entry ]
368
369 =over 4
370
371 =item *
372
373 Perl no longer panics when switching into some locales on machines with
374 buggy C<strxfrm()> implementations in their libc. [perl #121734]
375
376 =back
377
378 =head1 Selected Bug Fixes
379
380 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
381 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
382
383 [ List each fix as a =item entry ]
384
385 =over 4
386
387 =item *
388
389 C< until ($x = 1) { ... } > and C< ... until $x = 1 > now properly
390 warn when syntax warnings are enabled.  [perl #127333]
391
392 =back
393
394 =head1 Known Problems
395
396 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
397 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
398 platform specific bugs also go here.
399
400 [ List each fix as a =item entry ]
401
402 =over 4
403
404 =item *
405
406 XXX
407
408 =back
409
410 =head1 Errata From Previous Releases
411
412 =over 4
413
414 =item *
415
416 XXX Add anything here that we forgot to add, or were mistaken about, in
417 the perldelta of a previous release.
418
419 =back
420
421 =head1 Obituary
422
423 XXX If any significant core contributor has died, we've added a short obituary
424 here.
425
426 =head1 Acknowledgements
427
428 XXX Generate this with:
429
430   perl Porting/acknowledgements.pl v5.25.1..HEAD
431
432 =head1 Reporting Bugs
433
434 If you find what you think is a bug, you might check the articles recently
435 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
436 L<https://rt.perl.org/> .  There may also be information at
437 L<http://www.perl.org/> , the Perl Home Page.
438
439 If you believe you have an unreported bug, please run the L<perlbug> program
440 included with your release.  Be sure to trim your bug down to a tiny but
441 sufficient test case.  Your bug report, along with the output of C<perl -V>,
442 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
443
444 If the bug you are reporting has security implications which make it
445 inappropriate to send to a publicly archived mailing list, then see
446 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
447 for details of how to report the issue.
448
449 =head1 SEE ALSO
450
451 The F<Changes> file for an explanation of how to view exhaustive details on
452 what changed.
453
454 The F<INSTALL> file for how to build Perl.
455
456 The F<README> file for general stuff.
457
458 The F<Artistic> and F<Copying> files for copyright information.
459
460 =cut