This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
revise and reorder the perldelta template
[perl5.git] / Porting / perldelta_template.pod
index 1bf8c57..56f2f50 100644 (file)
@@ -12,14 +12,30 @@ perldelta - what is new for perl v5.XXX.XXX
 This document describes differences between the 5.XXX.XXX release and
 the 5.XXX.XXX release.
 
 This document describes differences between the 5.XXX.XXX release and
 the 5.XXX.XXX release.
 
-If you are upgrading from an earlier release such as 5.XXX.XXX, first read
-L<perl5XXXdelta>, which describes differences between 5.XXX.XXX and
-5.XXX.XXX.
+If you are upgrading from an earlier release such as 5.YYY.YYY, first read
+L<perl5YYYdelta>, which describes differences between 5.ZZZ.ZZZ and
+5.YYY.YYY.
 
 =head1 Notice
 
 XXX Any important notices here
 
 
 =head1 Notice
 
 XXX Any important notices here
 
+=head1 Core Enhancements
+
+XXX New core language features go here. Summarise user-visible core language
+enhancements. Particularly prominent performance optimisations could go
+here, but most should go in the L</Performance Enhancements> section.
+
+[ List each enhancement as a =head2 entry ]
+
+=head1 Security
+
+XXX Any security-related notices go here.  In particular, any security
+vulnerabilities closed should be noted here rather than in the
+L</Selected Bug Fixes> section.
+
+[ List each security issue as a =head2 entry ]
+
 =head1 Incompatible Changes
 
 XXX For a release on a stable branch, this section aspires to be:
 =head1 Incompatible Changes
 
 XXX For a release on a stable branch, this section aspires to be:
@@ -27,19 +43,30 @@ XXX For a release on a stable branch, this section aspires to be:
     There are no changes intentionally incompatible with 5.XXX.XXX. If any
     exist, they are bugs and reports are welcome.
 
     There are no changes intentionally incompatible with 5.XXX.XXX. If any
     exist, they are bugs and reports are welcome.
 
+[ List each incompatible change as a =head2 entry ]
 
 
-=head1 Core Enhancements
+=head1 Deprecations
 
 
-XXX New core language features go here. Summarise user-visible core language
-enhancements. Particularly prominent performance optimisations could go
-here, but most should go in the L</Performance Enhancements> section.
+XXX Any deprecated features, syntax, modules etc. should be listed here.
+In particular, deprecated modules should be listed here even if they are
+listed as an updated module in the L</Modules and Pragmata> section.
 
 
-=head1 New Platforms
+[ List each deprecation as a =head2 entry ]
 
 
-XXX List any platforms that this version of perl compiles on, that previous
-versions did not. These will either be enabled by new files in the F<hints/>
-directories, or new subdirectories and F<README> files at the top level of the
-source tree.
+=head1 Performance Enhancements
+
+XXX Changes which enhance performance without changing behaviour go here. There
+may well be none in a stable release.
+
+[ List each enhancement as a =item entry ]
+
+=over 4
+
+=item *
+
+XXX
+
+=back
 
 =head1 Modules and Pragmata
 
 
 =head1 Modules and Pragmata
 
@@ -51,28 +78,46 @@ below.  A paragraph summary for important changes should then be added by hand.
 In an ideal world, dual-life modules would have a F<Changes> file that could be
 cribbed.
 
 In an ideal world, dual-life modules would have a F<Changes> file that could be
 cribbed.
 
+[ Within each section, list entries as a =item entry ]
+
 =head2 New Modules and Pragmata
 
 =head2 New Modules and Pragmata
 
-=head2 Pragmata Changes
+=over 4
 
 
-=head2 Updated Modules
+=item *
 
 
-=head2 Removed Modules and Pragmata
+XXX
 
 
-=head1 Utility Changes
+=back
 
 
-XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
-here. Most of these are built within the directories F<utils> and F<x2p>.
+=head2 Updated Modules and Pragmata
 
 =over 4
 
 
 =over 4
 
-=item F<XXX>
+=item *
+
+XXX
+
+=back
+
+=head2 Removed Modules and Pragmata
+
+=over 4
+
+=item *
 
 XXX
 
 =back
 
 
 XXX
 
 =back
 
-=head1 New Documentation
+=head1 Documentation
+
+XXX Changes to files in F<pod/> go here.  Consider grouping entries by
+file and be sure to link to the appropriate page, e.g. L<perlfunc>.
+
+[ Within each section, list entries as a =item entry ]
+
+=head2 New Documentation
 
 XXX Changes which create B<new> files in F<pod/> go here.
 
 
 XXX Changes which create B<new> files in F<pod/> go here.
 
@@ -84,16 +129,34 @@ XXX
 
 =back
 
 
 =back
 
-=head1 Changes to Existing Documentation
+=head2 Changes to Existing Documentation
 
 XXX Changes which significantly change existing files in F<pod/> go here.
 
 XXX Changes which significantly change existing files in F<pod/> go here.
-Any changes to F<pod/perldiag.pod> should go in L</New or Changed Diagnostics>.
+However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
+section.
 
 
+=over 4
 
 
-=head1 Performance Enhancements
+=item L<XXX>
 
 
-XXX Changes which enhance performance without changing behaviour go here. There
-may well be none in a stable release.
+XXX
+
+=back
+
+=head1 Diagnostics
+
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see L<perldiag>.
+
+XXX New or changed warnings emitted by the core's C<C> code go here. Also
+include any changes in L<perldiag> that reconcile it to the C<C> code.
+
+[ Within each section, list entries as a =item entry ]
+
+=head2 New Diagnostics
+
+XXX Newly added diagnostic messages go here
 
 =over 4
 
 
 =over 4
 
@@ -103,34 +166,60 @@ XXX
 
 =back
 
 
 =back
 
-=head1 Installation and Configuration Improvements
+=head2 Changes to Existing Diagnostics
 
 
-XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
-go here.
+XXX Changes (i.e. rewording) of diagnostic messages go here
 
 
-=head2 Configuration improvements
+=over 4
+
+=item *
 
 XXX
 
 
 XXX
 
-=head2 Compilation improvements
+=back
+
+=head1 Utility Changes
+
+XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
+here. Most of these are built within the directories F<utils> and F<x2p>.
+
+[ List utility changes as a =item entry.  Use L<XXX> with program names to get
+proper documentation linking. ]
+
+=over 4
+
+=item L<XXX>
 
 XXX
 
 
 XXX
 
-=head2 Platform Specific Changes
+=back
+
+=head1 Configuration and Compilation
+
+XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
+go here.  Any other changes to the Perl build process should be listed here.
+However, any platform-specific changes should be listed in the
+L</Platform Support> section, instead.
+
+[ List changes as a =item entry ].
 
 =over 4
 
 
 =over 4
 
-=item XXX-some-platform
+=item *
 
 XXX
 
 =back
 
 
 XXX
 
 =back
 
-=head1 Selected Bug Fixes
+=head1 Testing
 
 
-XXX Important bug fixes in the core language are summarised here.
-Bug fixes in files in F<ext/> and F<lib/> are best summarised in
-L</Modules and Pragmata>.
+XXX Any significant changes to the testing of a freshly built perl should be
+listed here.  Changes which create B<new> files in F<t/> go here as do any
+large changes to the testing harness (e.g. when parallel testing was added).
+Changes to existing files in F<t/> aren't worth summarising, although the bugs
+that they represent may be covered elsewhere.
+
+[ List each test improvement as a =item entry ]
 
 =over 4
 
 
 =over 4
 
@@ -140,52 +229,62 @@ XXX
 
 =back
 
 
 =back
 
-=head1 New or Changed Diagnostics
+=head1 Platform Support
+
+XXX Any changes to platform support should be listed in the sections below.
+
+[ Within the sections, list each platform as a =item entry with specific
+changes as paragraphs below it. ]
+
+=head2 New Platforms
 
 
-XXX New or changed warnings emitted by the core's C<C> code go here.
+XXX List any platforms that this version of perl compiles on, that previous
+versions did not. These will either be enabled by new files in the F<hints/>
+directories, or new subdirectories and F<README> files at the top level of the
+source tree.
 
 =over 4
 
 
 =over 4
 
-=item C<XXX>
+=item XXX-some-platform
 
 XXX
 
 =back
 
 
 XXX
 
 =back
 
-=head1 Changed Internals
+=head2 Discontinued Platforms
 
 
-XXX Changes which affect the interface available to C<XS> code go here.
+XXX List any platforms that this version of perl no longer compiles on.
 
 =over 4
 
 
 =over 4
 
-=item *
+=item XXX-some-platform
 
 XXX
 
 =back
 
 
 XXX
 
 =back
 
-=head1 New Tests
+=head2 Platform-Specific Notes
 
 
-XXX Changes which create B<new> files in F<t/> go here. Changes to
-existing files in F<t/> aren't worth summarising, although the bugs that
-they represent may be.
+XXX List any changes for specific platforms. This could include configuration
+and compilation changes or changes in portability/compatibility.  However,
+changes within modules for platforms should generally be listed in the
+L</Modules and Pragmata> section.
 
 =over 4
 
 
 =over 4
 
-=item F<XXX>
+=item XXX-some-platform
 
 XXX
 
 =back
 
 
 XXX
 
 =back
 
-=head1 Known Problems
+=head1 Internal Changes
 
 
-XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
-tests that had to be C<TODO>ed for the release would be noted here, unless
-they were specific to a particular platform (see below).
+XXX Changes which affect the interface available to C<XS> code go here.
+Other significant internal changes for future core maintainers should
+be noted as well.
 
 
-This is a list of some significant unfixed bugs, which are regressions
-from either 5.XXX.XXX or 5.XXX.XXX.
+[ List each test improvement as a =item entry ]
 
 =over 4
 
 
 =over 4
 
@@ -195,11 +294,13 @@ XXX
 
 =back
 
 
 =back
 
-=head1 Deprecations
+=head1 Selected Bug Fixes
 
 
-XXX Add any new known deprecations here.
+XXX Important bug fixes in the core language are summarised here.
+Bug fixes in files in F<ext/> and F<lib/> are best summarised in
+L</Modules and Pragmata>.
 
 
-The following items are now deprecated.
+[ List each fix as a =item entry ]
 
 =over 4
 
 
 =over 4
 
@@ -209,11 +310,24 @@ XXX
 
 =back
 
 
 =back
 
-=head1 Platform Specific Notes
+=head1 Known Problems
 
 
-XXX Any changes specific to a particular platform. VMS and Win32 are the usual
-stars here. It's probably best to group changes under the same section layout
-as the main perldelta
+XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
+tests that had to be C<TODO>ed for the release would be noted here, unless
+they were specific to a particular platform (see below).
+
+This is a list of some significant unfixed bugs, which are regressions
+from either 5.XXX.XXX or 5.XXX.XXX.
+
+[ List each fix as a =item entry ]
+
+=over 4
+
+=item *
+
+XXX
+
+=back
 
 =head1 Obituary
 
 
 =head1 Obituary
 
@@ -224,7 +338,6 @@ here.
 
 XXX The list of people to thank goes here.
 
 
 XXX The list of people to thank goes here.
 
-
 =head1 Reporting Bugs
 
 If you find what you think is a bug, you might check the articles
 =head1 Reporting Bugs
 
 If you find what you think is a bug, you might check the articles