how_to_write_a_perldelta.pod: sections to match skeleton, more detail

1 files changed, 106 insertions, 53 deletions

diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod
index ec0385caab..f221d75ac7 100644
--- a/Porting/how_to_write_a_perldelta.pod
+++ b/Porting/how_to_write_a_perldelta.pod
@@ -8,13 +8,20 @@ This is intended as a guide for how to write a perldelta. There has never
 been a formal specification - the working rule is "fake up a document that
 looks something close to the existing perldeltas". So if it's unclear how
 to do something, see if it's been done before, and if the approach works
-there, steal it.
+there, steal it. (L<perl5300delta> and L<perl5320delta> are both quite
+lengthy and contain good examples for many of the perldelta sections.)
 
-=head2 Template
+=head2 Template Automation
 
-Note there is a file F<Porting/perldelta_template.pod> which contains a
-skeleton version of a perldelta.pod file, which should normally be copied
-in at the start of a new release.
+Note that F<Porting/perldelta_template.pod> contains a skeleton version of 
+a perldelta.pod file. Following the steps in the Release Manager's Guide
+(F<Porting/release_managers_guide.pod>) usually ensures hassle-free 
+rotation of the most recently completed perldelta.pod and preparation of
+a fresh new document ready for the next release.
+
+The skeleton document also contains inline hints on how to prepare the
+final perldelta.pod. (These hints should be removed in turn as each section
+of the final perldelta.pod is completed.)
 
 =head2 Style
 
@@ -39,6 +46,10 @@ Be consistent in how bugs are referenced. One style is
 
 =over 4
 
+=item GitHub
+
+C<[GH #12345]> can be used to reference both Issues and Pull Requests.
+
 =item rt.cpan.org
 
 C<rt.cpan.org #43010> inline, but enclose in square brackets after a sentence.
@@ -89,14 +100,38 @@ For the start of a new stable branch, follows this formula:
     This document describes differences between the 5.10.0 release
     and the 5.12.0 release.
 
-Clearly this sets the scope of which changes are to be summarised in the rest
-of the document.
+This clearly sets the scope of which changes are to be summarized in the
+rest of the document.
+
+For all releases, a second paragraph points to the previous perldelta:
+
+    If you are upgrading from an earlier release such as 5.rXXX.aXXX,
+    first read perl5XXXdelta, which describes differences between
+    5.rXXX.aXXX and 5.sXXX.bXXX.
 
 =item Notice
 
 There was a I<Notice> section in L<perl589delta>, to carry an important
 notice.
 
+=item Core Enhancements
+
+New core language features go here. Summarize user-visible core language
+enhancements. Particularly prominent performance optimisations could go
+here, but most should go in the L</Performance Enhancements> section.
+
+Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
+
+=item Security
+
+Any security-related notices go here. In particular, any security
+vulnerabilities closed should be noted here rather than in the
+"Selected Bug Fixes" section.
+
+L<perl5303delta> has multiple such examples, as well as
+a useful accompanying paragraph outlining the known attack
+vectors / requirements for the vulnerabilities to be exploitable.
+
 =item Incompatible Changes
 
 For a release on a stable branch, this section aspires to be
@@ -104,20 +139,20 @@ For a release on a stable branch, this section aspires to be
     There are no changes intentionally incompatible with 5.10.3.
     If any exist, they are bugs and reports are welcome.
 
-=item Core Enhancements
+Otherwise, changes should be listed as =head2 entries.
 
-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.
+=item Deprecations
 
-Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
+Add any new known deprecations (features, syntax, modules) here.
 
-=item New Platforms
+A I<Module removals> subsection can be used to foreshadow planned removal
+of core modules in a future release. Modules that were actually removed
+in this release should go in the "Modules and Pragmata" section.
 
-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.
+=item Performance Enhancements
+
+Changes which enhance performance without changing behaviour go here. There
+may well be none in a stable release.
 
 =item Modules and Pragmata
 
@@ -129,7 +164,7 @@ have a F<Changes> file that could be cribbed.
 
 Whilst this section could be built by incrementally working through change
 descriptions applying to files, this is prone to error. It's better to
-collate changes by module, and then summarise all changes to a module as a
+collate changes by module, and then summarize all changes to a module as a
 group.
 
 If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
@@ -137,8 +172,7 @@ will automatically update two sections in F<perldelta>:
 
     * New Modules and Pragmata
     * Updated Modules and Pragmata
-
-(Currently, it does not update the Removed Modules and Pragmata section.)
+    * Removed Modules and Pragmata
 
 Each section will have stub entries following a template like this:
 
@@ -153,16 +187,11 @@ added by hand.
 A more adventurous enhancement would be to automate grabbing
 the changelogs for dual lived modules. For each of them, grab the relevant
 changes files from CPAN for the old and new versions, and if the old one is
-a strict subset of the new one, use the extra lines as a basis for summarising.
+a strict subset of the new one, use the extra lines as a basis for summarizing.
 
 (And if not, experiment with using F<git> to get the relevant part of changelog
 for the particular file in core.)
 
-=item Utility Changes
-
-Changes to installed programs such as F<perldoc> and F<xsubpp> go here. Most
-of these are built within the directory F<utils>.
-
 =item New Documentation
 
 Changes which create B<new> files in F<pod/> go here.
@@ -226,57 +255,77 @@ Write out a block of text starting roughly
 
 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>.
-
-=item Performance Enhancements
+L</New Diagnostics> or L</Changed Diagnostics>.
 
-Changes which enhance performance without changing behaviour go here. There
-may well be none in a stable release.
+=item New Diagnostics
 
-=item Installation and Configuration Improvements
-
-Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
-go here.
+New warnings emitted by the core's C<C> code go here.
 
-=item Selected Bug Fixes
+=item Changed Diagnostics
 
-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>.
+Changed warnings emitted by the core's C<C> code go here.
 
-=item New or Changed Diagnostics
+=item Utility Changes
 
-New or changed warnings emitted by the core's C<C> code go here.
+Changes to installed programs such as F<perldoc> and F<xsubpp> go here. Most
+of these are built within the directory F<utils>.
 
-=item Changed Internals
+=item Configuration and Compilation
 
-Changes which affect the interface available to C<XS> code go here.
+Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
+go here.
 
-=item New Tests
+=item Testing
 
 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
+in F<t/> aren't worth summarizing, although the bugs that they represent
 may be.
 
 Autogenerate this section by running something like this:
 
  # perl newtests-perldelta.pl v5.11.1 HEAD
 
+=item Platform Support
+
+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.
+
+=item New Platforms
+
+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.
+
+=item Discontinued Platforms
+
+List any platforms that this version of perl no longer compiles on. The
+reverse of the advice above applies - look for removed hints or README files.
+
+=item Platform-Specific Notes
+
+Changes of note to specific platforms go here.
+
+=item Internal Changes
+
+Changes which affect the interface available to C<XS> code go here.
+
+=item Selected Bug Fixes
+
+Important bug fixes in the core language are summarized here.
+Bug fixes in files in F<ext/> and F<lib/> are best summarized in
+L</Modules and Pragmata>.
+
 =item Known Problems
 
 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).
 
-=item Deprecations
-
-Add any new known deprecations here.
+=item Errata From Previous Releases
 
-=item Platform Specific Notes
-
-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.
+XXXXXXXXXX TODO
 
 =item Obituary
 
@@ -293,6 +342,10 @@ Generate this with:
 
 This doesn't usually need to be changed from the previous perldelta.
 
+=item Give Thanks
+
+This doesn't usually need to be changed from the previous perldelta.
+
 =item SEE ALSO
 
 This doesn't usually need to be changed from the previous perldelta.