This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
9459525f328e3c200c82c2005a533aa1a8805167
[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.27.8
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.27.7 release and the 5.27.8
13 release.
14
15 If you are upgrading from an earlier release such as 5.27.6, first read
16 L<perl5277delta>, which describes differences between 5.27.6 and 5.27.7.
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 Close-on-exec flag set atomically
31
32 When opening a file descriptor, perl now generally opens it with its
33 close-on-exec flag already set, on platforms that support doing so.
34 This improves thread safety, because it means that an C<exec> initiated
35 by one thread can no longer cause a file descriptor in the process
36 of being opened by another thread to be accidentally passed to the
37 executed program.
38
39 Additionally, perl now sets the close-on-exec flag more reliably, whether
40 it does so atomically or not.  Most file descriptors were getting the
41 flag set, but some were being missed.
42
43 =head2 Mixed Unicode scripts are now detectable
44
45 A mixture of scripts, such as Cyrillic and Latin, in a string is often
46 the sign of a spoofing attack.  A new regular expression construct
47 now allows for easy detection of these.  For example, you can say
48
49  qr/(?script_run: \d+ \b )/x
50
51 And the digits matched will all be from the same set of 10.  You won't
52 get a look-alike digit from a different script that has a different
53 value than what it appears to be.
54
55 =head1 Security
56
57 XXX Any security-related notices go here.  In particular, any security
58 vulnerabilities closed should be noted here rather than in the
59 L</Selected Bug Fixes> section.
60
61 [ List each security issue as a =head2 entry ]
62
63 =head1 Incompatible Changes
64
65 XXX For a release on a stable branch, this section aspires to be:
66
67     There are no changes intentionally incompatible with 5.XXX.XXX
68     If any exist, they are bugs, and we request that you submit a
69     report.  See L</Reporting Bugs> below.
70
71 [ List each incompatible change as a =head2 entry ]
72
73 =head1 Deprecations
74
75 XXX Any deprecated features, syntax, modules etc. should be listed here.
76
77 =head2 Module removals
78
79 XXX Remove this section if not applicable.
80
81 The following modules will be removed from the core distribution in a
82 future release, and will at that time need to be installed from CPAN.
83 Distributions on CPAN which require these modules will need to list them as
84 prerequisites.
85
86 The core versions of these modules will now issue C<"deprecated">-category
87 warnings to alert you to this fact.  To silence these deprecation warnings,
88 install the modules in question from CPAN.
89
90 Note that these are (with rare exceptions) fine modules that you are encouraged
91 to continue to use.  Their disinclusion from core primarily hinges on their
92 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
93 not usually on concerns over their design.
94
95 =over
96
97 =item XXX
98
99 XXX Note that deprecated modules should be listed here even if they are listed
100 as an updated module in the L</Modules and Pragmata> section.
101
102 =back
103
104 [ List each other deprecation as a =head2 entry ]
105
106 =head1 Performance Enhancements
107
108 XXX Changes which enhance performance without changing behaviour go here.
109 There may well be none in a stable release.
110
111 [ List each enhancement as an =item entry ]
112
113 =over 4
114
115 =item *
116
117 XXX
118
119 =back
120
121 =head1 Modules and Pragmata
122
123 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
124 go here.  If Module::CoreList is updated, generate an initial draft of the
125 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
126 for important changes should then be added by hand.  In an ideal world,
127 dual-life modules would have a F<Changes> file that could be cribbed.
128
129 The list of new and updated modules is modified automatically as part of
130 preparing a Perl release, so the only reason to manually add entries here is if
131 you're summarising the important changes in the module update. (Also, if the
132 manually-added details don't match the automatically-generated ones, the
133 release manager will have to investigate the situation carefully.)
134
135 [ Within each section, list entries as an =item entry ]
136
137 =head2 New Modules and Pragmata
138
139 =over 4
140
141 =item *
142
143 XXX Remove this section if not applicable.
144
145 =back
146
147 =head2 Updated Modules and Pragmata
148
149 =over 4
150
151 =item *
152
153 L<XXX> has been upgraded from version A.xx to B.yy.
154
155 If there was something important to note about this change, include that here.
156
157 =back
158
159 =head2 Removed Modules and Pragmata
160
161 =over 4
162
163 =item *
164
165 XXX
166
167 =back
168
169 =head1 Documentation
170
171 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
172 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
173
174 =head2 New Documentation
175
176 XXX Changes which create B<new> files in F<pod/> go here.
177
178 =head3 L<XXX>
179
180 XXX Description of the purpose of the new file here
181
182 =head2 Changes to Existing Documentation
183
184 We have attempted to update the documentation to reflect the changes
185 listed in this document.  If you find any we have missed, send email
186 to L<perlbug@perl.org|mailto:perlbug@perl.org>.
187
188 XXX Changes which significantly change existing files in F<pod/> go here.
189 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
190 section.
191
192 Additionally, the following selected changes have been made:
193
194 =head3 L<XXX>
195
196 =over 4
197
198 =item *
199
200 XXX Description of the change here
201
202 =back
203
204 =head1 Diagnostics
205
206 The following additions or changes have been made to diagnostic output,
207 including warnings and fatal error messages.  For the complete list of
208 diagnostic messages, see L<perldiag>.
209
210 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
211 include any changes in L<perldiag> that reconcile it to the C<C> code.
212
213 =head2 New Diagnostics
214
215 XXX Newly added diagnostic messages go under here, separated into New Errors
216 and New Warnings
217
218 =head3 New Errors
219
220 =over 4
221
222 =item *
223
224 XXX L<message|perldiag/"message">
225
226 =back
227
228 =head3 New Warnings
229
230 =over 4
231
232 =item *
233
234 XXX L<message|perldiag/"message">
235
236 =back
237
238 =head2 Changes to Existing Diagnostics
239
240 XXX Changes (i.e. rewording) of diagnostic messages go here
241
242 =over 4
243
244 =item *
245
246 XXX Describe change here
247
248 =back
249
250 =head1 Utility Changes
251
252 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
253 Most of these are built within the directory F<utils>.
254
255 [ List utility changes as a =head2 entry for each utility and =item
256 entries for each change
257 Use L<XXX> with program names to get proper documentation linking. ]
258
259 =head2 L<XXX>
260
261 =over 4
262
263 =item *
264
265 XXX
266
267 =back
268
269 =head1 Configuration and Compilation
270
271 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
272 go here.  Any other changes to the Perl build process should be listed here.
273 However, any platform-specific changes should be listed in the
274 L</Platform Support> section, instead.
275
276 [ List changes as an =item entry ].
277
278 =over 4
279
280 =item *
281
282 XXX
283
284 =back
285
286 =head1 Testing
287
288 XXX Any significant changes to the testing of a freshly built perl should be
289 listed here.  Changes which create B<new> files in F<t/> go here as do any
290 large changes to the testing harness (e.g. when parallel testing was added).
291 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
292 that they represent may be covered elsewhere.
293
294 XXX If there were no significant test changes, say this:
295
296 Tests were added and changed to reflect the other additions and changes
297 in this release.
298
299 XXX If instead there were significant changes, say this:
300
301 Tests were added and changed to reflect the other additions and
302 changes in this release.  Furthermore, these significant changes were
303 made:
304
305 [ List each test improvement as an =item entry ]
306
307 =over 4
308
309 =item *
310
311 XXX
312
313 =back
314
315 =head1 Platform Support
316
317 XXX Any changes to platform support should be listed in the sections below.
318
319 [ Within the sections, list each platform as an =item entry with specific
320 changes as paragraphs below it. ]
321
322 =head2 New Platforms
323
324 XXX List any platforms that this version of perl compiles on, that previous
325 versions did not.  These will either be enabled by new files in the F<hints/>
326 directories, or new subdirectories and F<README> files at the top level of the
327 source tree.
328
329 =over 4
330
331 =item XXX-some-platform
332
333 XXX
334
335 =back
336
337 =head2 Discontinued Platforms
338
339 XXX List any platforms that this version of perl no longer compiles on.
340
341 =over 4
342
343 =item XXX-some-platform
344
345 XXX
346
347 =back
348
349 =head2 Platform-Specific Notes
350
351 XXX List any changes for specific platforms.  This could include configuration
352 and compilation changes or changes in portability/compatibility.  However,
353 changes within modules for platforms should generally be listed in the
354 L</Modules and Pragmata> section.
355
356 =over 4
357
358 =item XXX-some-platform
359
360 XXX
361
362 =back
363
364 =head1 Internal Changes
365
366 XXX Changes which affect the interface available to C<XS> code go here.  Other
367 significant internal changes for future core maintainers should be noted as
368 well.
369
370 [ List each change as an =item entry ]
371
372 =over 4
373
374 =item *
375
376 XXX
377
378 =back
379
380 =head1 Selected Bug Fixes
381
382 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
383 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
384
385 [ List each fix as an =item entry ]
386
387 =over 4
388
389 =item *
390
391 XXX
392
393 =back
394
395 =head1 Known Problems
396
397 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
398 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
399 platform specific bugs also go here.
400
401 [ List each fix as an =item entry ]
402
403 =over 4
404
405 =item *
406
407 XXX
408
409 =back
410
411 =head1 Errata From Previous Releases
412
413 =over 4
414
415 =item *
416
417 XXX Add anything here that we forgot to add, or were mistaken about, in
418 the perldelta of a previous release.
419
420 =back
421
422 =head1 Obituary
423
424 XXX If any significant core contributor or member of the CPAN community has
425 died, add a short obituary here.
426
427 =head1 Acknowledgements
428
429 XXX Generate this with:
430
431   perl Porting/acknowledgements.pl v5.27.7..HEAD
432
433 =head1 Reporting Bugs
434
435 If you find what you think is a bug, you might check the perl bug database
436 at 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 Give Thanks
450
451 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
452 you can do so by running the C<perlthanks> program:
453
454     perlthanks
455
456 This will send an email to the Perl 5 Porters list with your show of thanks.
457
458 =head1 SEE ALSO
459
460 The F<Changes> file for an explanation of how to view exhaustive details on
461 what changed.
462
463 The F<INSTALL> file for how to build Perl.
464
465 The F<README> file for general stuff.
466
467 The F<Artistic> and F<Copying> files for copyright information.
468
469 =cut