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.

Historically,
the perldelta has consisted of a sequence of =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.

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 hints/ directories, or new subdirectories and README files at the top level of the source tree.

All changes to installed files in ext/ and lib/ 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 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 to ext/ and lib/ by module, and then summarise all changes to a module as a group. This can be done by partitioning directories within ext/ and lib/ to a number of people.

FIXME - this could be automated better

If Module::CoreList has been updated, then Porting/corelist-perldelta.pl will automatically print out several sections if relevant that can be pasted into perldelta:

It does not include modules listed in Porting/Maintainers.pl under _PERLLIB, but it's a start. Where relevant, 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 git 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 perl${whatever}delta.pod, and splicing in the updates correctly without throwing existing entries away.

If you think that's nuts, take a look at what pod/buildtoc already does to splice into existing Makefiles on various platforms:

Descriptions of platform agnostic bugs we know we can't fix go here. Any tests that had to be TODOed for the release would be noted here, unless they were specific to a particular platform (see below).