From: Nicholas Clark Date: Thu, 28 May 2009 13:15:53 +0000 (+0100) Subject: Add a guide to writing a perldelta. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=20a4c497f5b0005c2471e3b5ae0d1bb1744fa871;p=p5sagit%2Fp5-mst-13.2.git Add a guide to writing a perldelta. --- diff --git a/MANIFEST b/MANIFEST index 8006cd7..0903a46 100644 --- a/MANIFEST +++ b/MANIFEST @@ -3708,6 +3708,7 @@ Porting/genlog Generate formatted changelogs by querying p4d Porting/git-find-p4-change Find the change for a p4 change number Porting/git-make-p4-refs Output git refs for each p4 change number, suitable for appending to .git/packed-refs Porting/Glossary Glossary of config.sh variables +Porting/how_to_write_a_perldelta.pod Bluffer's guide to writing a perldelta. Porting/Maintainers Program to pretty print info in Maintainers.pl Porting/Maintainers.pl Information about maintainers Porting/Maintainers.pm Library to pretty print info in Maintainers.pl diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod new file mode 100644 index 0000000..5f32312 --- /dev/null +++ b/Porting/how_to_write_a_perldelta.pod @@ -0,0 +1,199 @@ +=head1 How to write a perldelta + +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 +do to do something, see if it's been done before, and if the approach works +there, steal it. + +=head2 Style + +Pod is more a physical markup language, rather than a logical markup language. +Despite that it has some built in conventions. B: + +=over 4 + +=item * CE> is for File + +=item * CE> is for Code + +=item * CE> is for Link + +=back + +Whilst modules could also be links, usually in the context of the perldelta +the reference is to code Cing them, rather than something within their +documentation. + +Be consistent in how bugs are referenced. One style is + +=over 4 + +=item rt.perl.org + +C inline, but enclose in square brackets after a sentence. +C<[RT #43010]> + +=item ActiveState + +C + +=item Debian + +C + +=back + +=head2 Copy editing + +Be consistent. + +In a list, either make every item a note, or a full sentence. Either end +every item with a full stop, or ensure that no item ends with one. + +=head2 Sections + +Historically, the perldelta has consisted of a sequence of C<=head1> +sections, usually in the same order. Un-needed sections are deleted, +and if something doesn't fit nicely into the existing sections, a new +more appropriate section is created. + +=over + +=item NAME + +Follows this formula: + + perl5104delta - what is new for perl v5.10.4 + +=item DESCRIPTION + +For a release on a stable branch, follows this formula: + + This document describes differences between the 5.10.3 release and + the 5.10.4 release. + +For the start of a new stable branch, follows this formula: + + This document describes differences between the 5.12.0 release and + the 5.10.0 release. + +Clearly this sets the scope of which changes are to be summarise in the rest +of the document. + +=item Notice + +There was a I section in L, to carry an important +notice. + +=item Incompatible Changes + +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 + +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 section. + +Feature inside modules (pure-Perl and XS) go in L + +=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 +directories, or new subdirectories and F files at the top level of the +source tree. + +=item Modules and Pragmata + +All changes to installed files in F and F go here, in a list +ordered by distribution name. Minimally it should be the module version, +but it's more useful to the end user to give a paragraph's summary of the +module's changes. In an ideal world, dual-life modules would have a +F 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 to F and F by module, and then summarise all +changes to a module as a group. This can be done by partitioning directories +within F and F to a number of people. + +=item Utility Changes + +Changes to installed programs such as F and F go here. Most +of these are built within the directories F and F. + +=item New Documentation + +Changes which create B files in F go here. + +=item Changes to Existing Documentation + +Changes which significantly change existing files in F go here. +Any changes to F should go in +L. + +=item Performance Enhancements + +Changes which enhance performance without changing behaviour go here. There +may well be none in a stable release. + +=item Installation and Configuration Improvements + +Changes to F, F, F, and analogous tools +go here. + +=item Selected Bug Fixes + +Important bug fixes in the core language are summarised here. +Bug fixes in files in F and F are best summarised in +L. + +=item New or Changed Diagnostics + +New or changed warnings emitted by the core's C code go here. + +=item Changed Internals + +Changes which affect the interface available to C code go here. + +=item New Tests + +Changes which create B files in F go here. Changes to existing files +in F aren't worth summarising, although the bugs that they represent +may be. + +=item Known Problems + +Descriptions of platform agnostic bugs we know we can't fix go here. Any +tests that had to be Ced for the release would be noted here, unless +they were specific to a particular platform (see below). + +=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. + +=item Obituary + +If any significant core contributor has died, we've added a short obituary +here. + +=item Acknowledgements + +The list of people to thank goes here. + +=item Reporting Bugs + +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. + +=back