=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 Template Note there is a file F which contains a skeleton version of a perldelta.pod file, which should normally be copied in at the start of a new release. =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. I B I - choose exactly one, and stick to it. =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 summarised 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. B - this could be automated better If Module::CoreList has been updated, then F will automatically print out several sections if relevent that can be pasted into F: * New Modules and Pragmata * Pragmata Changes * Updated Modules * Removed Modules and Pragmata Each section will have stub entries following a template like this: =item C Upgraded from version 0.01 to 0.02 It does not include modules listed in F under C<_PERLLIB>, but it's a start. Where relevent, a summary of changes can be 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, splice the extra lines right into the output, as a basis for summarising. (And if not, experiment with using F to get the relevant part of changelog for the particular file in core) These could also be enhanced further by using a Pod parser module to produce a parse tree of F, and splicing in the updates correctly without throwing existing entries away. If you think that's nuts, take a look at what F already does to splice into existing Makefiles on various platforms: http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498 Perl is this really powerful language for text manipulation. And fun to play with. We need to get that message out. :-) =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. B - this could be automated, at least as far as generating a first draft. =over =item 1 Start with a clean exploded tarball of the previous release, and a clean checkout of the branch in question =item 2 Take the F file of each =item 3 Search for lines matching C =item 4 Diff them =item 5 Explode if anyone deleted documentation. [No idea what the policy on that is yet] =item 6 For each file only in the newer F =over =item 1 Use F to determine its Author =item 2 Open the pod file itself =item 3 Grab the description section =item 4 Write out a block of text starting roughly L, by A. U. Thor, provides @description =back =back =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. Autogenerate this section by running something like this: # perl newtests-perldelta.pl v5.11.1 HEAD =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 Deprecations Add any new known deprecations here. =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. You can find the list of committers and authors by: % git log --pretty='format:%an' v5.11.1..HEAD | sort | uniq And how many files where changed by: % git diff --stat=200,200 v5.11.1..HEAD =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