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 XXX
 357
 358 =back
 359
 360 =head1 Selected Bug Fixes
 361
 362 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
 363 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
 364
 365 [ List each fix as a =item entry ]
 366
 367 =over 4
 368
 369 =item *
 370
 371 XXX
 372
 373 =back
 374
 375 =head1 Known Problems
 376
 377 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
 378 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
 379 platform specific bugs also go here.
 380
 381 [ List each fix as a =item entry ]
 382
 383 =over 4
 384
 385 =item *
 386
 387 XXX
 388
 389 =back
 390
 391 =head1 Obituary
 392
 393 XXX If any significant core contributor has died, we've added a short obituary
 394 here.
 395
 396 =head1 Acknowledgements
 397
 398 XXX Generate this with:
 399
 400   perl Porting/acknowledgements.pl v5.17.6..HEAD
 401
 402 =head1 Reporting Bugs
 403
 404 If you find what you think is a bug, you might check the articles recently
 405 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
 406 http://rt.perl.org/perlbug/ .  There may also be information at
 407 http://www.perl.org/ , the Perl Home Page.
 408
 409 If you believe you have an unreported bug, please run the L<perlbug> program
 410 included with your release.  Be sure to trim your bug down to a tiny but
 411 sufficient test case.  Your bug report, along with the output of C<perl -V>,
 412 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
 413
 414 If the bug you are reporting has security implications, which make it
 415 inappropriate to send to a publicly archived mailing list, then please send it
 416 to perl5-security-report@perl.org.  This points to a closed subscription
 417 unarchived mailing list, which includes all the core committers, who will be
 418 able to help assess the impact of issues, figure out a resolution, and help
 419 co-ordinate the release of patches to mitigate or fix the problem across all
 420 platforms on which Perl is supported.  Please only use this address for
 421 security issues in the Perl core, not for modules independently distributed on
 422 CPAN.
 423
 424 =head1 SEE ALSO
 425
 426 The F<Changes> file for an explanation of how to view exhaustive details on
 427 what changed.
 428
 429 The F<INSTALL> file for how to build Perl.
 430
 431 The F<README> file for general stuff.
 432
 433 The F<Artistic> and F<Copying> files for copyright information.
 434
 435 =cut