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.17.7
   9
  10 =head1 DESCRIPTION
  11
  12 This document describes differences between the 5.17.6 release and the 5.17.7
  13 release.
  14
  15 If you are upgrading from an earlier release such as 5.17.5, first read
  16 L<perl5176delta>, which describes differences between 5.17.5 and 5.17.6.
  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 =head1 Security
  31
  32 XXX Any security-related notices go here.  In particular, any security
  33 vulnerabilities closed should be noted here rather than in the
  34 L</Selected Bug Fixes> section.
  35
  36 [ List each security issue as a =head2 entry ]
  37
  38 =head1 Incompatible Changes
  39
  40 =head2 readline() with C<$/ = \N> now reads N characters, not N bytes
  41
  42 Previously, when reading from a stream with I/O layers such as
  43 C<encoding>, the readline() function, otherwise known as the C<< <> >>
  44 operator, would read I<N> bytes from the top-most layer. [perl #79960]
  45
  46 Now, I<N> characters are read instead.
  47
  48 There is no change in behaviour when reading from streams with no
  49 extra layers, since bytes map exactly to characters.
  50
  51 XXX For a release on a stable branch, this section aspires to be:
  52
  53     There are no changes intentionally incompatible with 5.XXX.XXX
  54     If any exist, they are bugs, and we request that you submit a
  55     report.  See L</Reporting Bugs> below.
  56
  57 [ List each incompatible change as a =head2 entry ]
  58
  59 =head1 Deprecations
  60
  61 XXX Any deprecated features, syntax, modules etc. should be listed here.  In
  62 particular, deprecated modules should be listed here even if they are listed as
  63 an updated module in the L</Modules and Pragmata> section.
  64
  65 [ List each deprecation as a =head2 entry ]
  66
  67 =head2 Various XS-callable functions are now deprecated
  68
  69 The following functions will be removed from a future version of Perl,
  70 and should not be used.  With participating C compilers (e.g., gcc),
  71 compiling any file that uses any of these will generate a warning.
  72 These were not intended for public use; there are equivalent, faster,
  73 macros for most of them.  See L<perlapi/Character classes>:
  74 C<is_uni_ascii>,
  75 C<is_uni_ascii_lc>,
  76 C<is_uni_blank>,
  77 C<is_uni_blank_lc>,
  78 C<is_uni_cntrl>,
  79 C<is_uni_cntrl_lc>,
  80 C<is_uni_idfirst_lc>,
  81 C<is_uni_space>,
  82 C<is_uni_space_lc>,
  83 C<is_uni_xdigit>,
  84 C<is_uni_xdigit_lc>,
  85 C<is_utf8_ascii>,
  86 C<is_utf8_blank>,
  87 C<is_utf8_cntrl>,
  88 C<is_utf8_idcont>,
  89 C<is_utf8_idfirst>,
  90 C<is_utf8_perl_space>,
  91 C<is_utf8_perl_word>,
  92 C<is_utf8_posix_digit>,
  93 C<is_utf8_space>,
  94 C<is_utf8_xdigit>.
  95 C<is_utf8_xidcont>,
  96 C<is_utf8_xidfirst>,
  97 C<to_uni_lower_lc>,
  98 C<to_uni_title_lc>,
  99 and
 100 C<to_uni_upper_lc>.
 101
 102 =head1 Performance Enhancements
 103
 104 XXX Changes which enhance performance without changing behaviour go here.
 105 There may well be none in a stable release.
 106
 107 [ List each enhancement as a =item entry ]
 108
 109 =over 4
 110
 111 =item *
 112
 113 XXX
 114
 115 =back
 116
 117 =head1 Modules and Pragmata
 118
 119 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
 120 go here.  If Module::CoreList is updated, generate an initial draft of the
 121 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
 122 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
 123 below.  A paragraph summary for important changes should then be added by hand.
 124 In an ideal world, dual-life modules would have a F<Changes> file that could be
 125 cribbed.
 126
 127 [ Within each section, list entries as a =item entry ]
 128
 129 =head2 New Modules and Pragmata
 130
 131 =over 4
 132
 133 =item *
 134
 135 XXX
 136
 137 =back
 138
 139 =head2 Updated Modules and Pragmata
 140
 141 =over 4
 142
 143 =item *
 144
 145 L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
 146 optional fifth parameter to C<TIEHASH> has been removed. This was intended
 147 to provide control of the callback used by C<gdbm*> functions in case of
 148 fatal errors (such as filesystem problems), but did not work (and could
 149 never have worked). No code on CPAN even attempted to use it. The callback
 150 is now always the previous default, C<croak>. Problems on some platforms with
 151 how the C<C> C<croak> function is called have also been resolved.
 152
 153 =back
 154
 155 =head2 Removed Modules and Pragmata
 156
 157 =over 4
 158
 159 =item *
 160
 161 XXX
 162
 163 =back
 164
 165 =head1 Documentation
 166
 167 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
 168 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
 169
 170 =head2 New Documentation
 171
 172 XXX Changes which create B<new> files in F<pod/> go here.
 173
 174 =head3 L<XXX>
 175
 176 XXX Description of the purpose of the new file here
 177
 178 =head2 Changes to Existing Documentation
 179
 180 XXX Changes which significantly change existing files in F<pod/> go here.
 181 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
 182 section.
 183
 184 =head3 L<perlapi/Character classes>
 185
 186 =over 4
 187
 188 =item *
 189
 190 There are quite a few macros callable from XS modules that classify
 191 characters into things like alphabetic, punctuation, etc.  More of these
 192 are now documented, including ones which work on characters whose code
 193 points are outside the Latin-1 range.
 194
 195 =back
 196
 197 =head1 Diagnostics
 198
 199 The following additions or changes have been made to diagnostic output,
 200 including warnings and fatal error messages.  For the complete list of
 201 diagnostic messages, see L<perldiag>.
 202
 203 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
 204 include any changes in L<perldiag> that reconcile it to the C<C> code.
 205
 206 =head2 New Diagnostics
 207
 208 XXX Newly added diagnostic messages go under here, separated into New Errors
 209 and New Warnings
 210
 211 =head3 New Errors
 212
 213 =over 4
 214
 215 =item *
 216
 217 XXX L<message|perldiag/"message">
 218
 219 =back
 220
 221 =head3 New Warnings
 222
 223 =over 4
 224
 225 =item *
 226
 227 XXX L<message|perldiag/"message">
 228
 229 =back
 230
 231 =head2 Changes to Existing Diagnostics
 232
 233 XXX Changes (i.e. rewording) of diagnostic messages go here
 234
 235 =over 4
 236
 237 =item *
 238
 239 XXX Describe change here
 240
 241 =back
 242
 243 =head1 Utility Changes
 244
 245 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
 246 Most of these are built within the directories F<utils> and F<x2p>.
 247
 248 [ List utility changes as a =head3 entry for each utility and =item
 249 entries for each change
 250 Use L<XXX> with program names to get proper documentation linking. ]
 251
 252 =head3 L<XXX>
 253
 254 =over 4
 255
 256 =item *
 257
 258 XXX
 259
 260 =back
 261
 262 =head1 Configuration and Compilation
 263
 264 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
 265 go here.  Any other changes to the Perl build process should be listed here.
 266 However, any platform-specific changes should be listed in the
 267 L</Platform Support> section, instead.
 268
 269 [ List changes as a =item entry ].
 270
 271 =over 4
 272
 273 =item *
 274
 275 XXX
 276
 277 =back
 278
 279 =head1 Testing
 280
 281 XXX Any significant changes to the testing of a freshly built perl should be
 282 listed here.  Changes which create B<new> files in F<t/> go here as do any
 283 large changes to the testing harness (e.g. when parallel testing was added).
 284 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
 285 that they represent may be covered elsewhere.
 286
 287 [ List each test improvement as a =item entry ]
 288
 289 =over 4
 290
 291 =item *
 292
 293 XXX
 294
 295 =back
 296
 297 =head1 Platform Support
 298
 299 XXX Any changes to platform support should be listed in the sections below.
 300
 301 [ Within the sections, list each platform as a =item entry with specific
 302 changes as paragraphs below it. ]
 303
 304 =head2 New Platforms
 305
 306 XXX List any platforms that this version of perl compiles on, that previous
 307 versions did not.  These will either be enabled by new files in the F<hints/>
 308 directories, or new subdirectories and F<README> files at the top level of the
 309 source tree.
 310
 311 =over 4
 312
 313 =item XXX-some-platform
 314
 315 XXX
 316
 317 =back
 318
 319 =head2 Discontinued Platforms
 320
 321 =over 4
 322
 323 =item BeOS
 324
 325 Support for BeOS has been removed.
 326
 327 =back
 328
 329 =head2 Platform-Specific Notes
 330
 331 XXX List any changes for specific platforms.  This could include configuration
 332 and compilation changes or changes in portability/compatibility.  However,
 333 changes within modules for platforms should generally be listed in the
 334 L</Modules and Pragmata> section.
 335
 336 =over 4
 337
 338 =item XXX-some-platform
 339
 340 XXX
 341
 342 =back
 343
 344 =head1 Internal Changes
 345
 346 XXX Changes which affect the interface available to C<XS> code go here.  Other
 347 significant internal changes for future core maintainers should be noted as
 348 well.
 349
 350 [ List each change as a =item entry ]
 351
 352 =over 4
 353
 354 =item *
 355
 356 SvUPGRADE() is no longer an expression. Originally this macro (and its
 357 underlying function, sv_upgrade()) were documented as boolean, although
 358 in reality they always croaked on error and never returned false. In 2005
 359 the documentation was updated to specify a void return value, but
 360 SvUPGRADE() was left always returning 1 for backwards compatibility. This
 361 has now been removed, and SvUPGRADE() is now a statement with no return
 362 value.
 363
 364 So this is now a syntax error:
 365
 366     if (!SvUPGRADE(sv)) { croak(...); }
 367
 368 If you have code like that, simply replace it with
 369
 370     SvUPGRADE(sv);
 371
 372 or to to avoid compiler warnings with older perls, possibly
 373
 374     (void)SvUPGRADE(sv);
 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 XXX
 390
 391 =back
 392
 393 =head1 Known Problems
 394
 395 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
 396 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
 397 platform specific bugs also go here.
 398
 399 [ List each fix as a =item entry ]
 400
 401 =over 4
 402
 403 =item *
 404
 405 XXX
 406
 407 =back
 408
 409 =head1 Obituary
 410
 411 XXX If any significant core contributor has died, we've added a short obituary
 412 here.
 413
 414 =head1 Acknowledgements
 415
 416 XXX Generate this with:
 417
 418   perl Porting/acknowledgements.pl v5.17.6..HEAD
 419
 420 =head1 Reporting Bugs
 421
 422 If you find what you think is a bug, you might check the articles recently
 423 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
 424 http://rt.perl.org/perlbug/ .  There may also be information at
 425 http://www.perl.org/ , the Perl Home Page.
 426
 427 If you believe you have an unreported bug, please run the L<perlbug> program
 428 included with your release.  Be sure to trim your bug down to a tiny but
 429 sufficient test case.  Your bug report, along with the output of C<perl -V>,
 430 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
 431
 432 If the bug you are reporting has security implications, which make it
 433 inappropriate to send to a publicly archived mailing list, then please send it
 434 to perl5-security-report@perl.org.  This points to a closed subscription
 435 unarchived mailing list, which includes all the core committers, who will be
 436 able to help assess the impact of issues, figure out a resolution, and help
 437 co-ordinate the release of patches to mitigate or fix the problem across all
 438 platforms on which Perl is supported.  Please only use this address for
 439 security issues in the Perl core, not for modules independently distributed on
 440 CPAN.
 441
 442 =head1 SEE ALSO
 443
 444 The F<Changes> file for an explanation of how to view exhaustive details on
 445 what changed.
 446
 447 The F<INSTALL> file for how to build Perl.
 448
 449 The F<README> file for general stuff.
 450
 451 The F<Artistic> and F<Copying> files for copyright information.
 452
 453 =cut