/ 
perl-5.10.1-RC1
River stage five • 11849 direct dependents • 33721 total dependents
/ Porting::how_to_write_a_perldelta

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.

Style

Pod is more a physical markup language, rather than a logical markup language. Despite that it has some built in conventions. Stick to them:

  • F<> is for File

  • C<> is for Code

  • L<> is for Link

Whilst modules could also be links, usually in the context of the perldelta the reference is to code useing them, rather than something within their documentation.

Be consistent in how bugs are referenced. One style is

rt.perl.org

RT #43010 inline, but enclose in square brackets after a sentence. [RT #43010]

ActiveState

http://bugs.activestate.com/show_bug.cgi?id=72443

Debian

Debian bug #379463

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. regex xor regexp - choose exactly one, and stick to it.

Sections

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.

NAME

Follows this formula:

perl5104delta - what is new for perl v5.10.4
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.

Notice

There was a Notice section in perl589delta, to carry an important notice.

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.
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 "Performance Enhancements" section.

Feature inside modules (pure-Perl and XS) go in "Modules and Pragmata"

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

Modules and Pragmata

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.

Utility Changes

Changes to installed programs such as perlbug and xsubpp go here. Most of these are built within the directories utils and x2p.

New Documentation

Changes which create new files in pod/ go here.

Changes to Existing Documentation

Changes which significantly change existing files in pod/ go here. Any changes to pod/perldiag.pod should go in "New or Changed Diagnostics".

Performance Enhancements

Changes which enhance performance without changing behaviour go here. There may well be none in a stable release.

Installation and Configuration Improvements

Changes to Configure, installperl, installman, and analogous tools go here.

Selected Bug Fixes

Important bug fixes in the core language are summarised here. Bug fixes in files in ext/ and lib/ are best summarised in "Modules and Pragmata".

New or Changed Diagnostics

New or changed warnings emitted by the core's C code go here.

Changed Internals

Changes which affect the interface available to XS code go here.

New Tests

Changes which create new files in t/ go here. Changes to existing files in t/ aren't worth summarising, although the bugs that they represent may be.

Known Problems

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).

Deprecations

Add any new known deprecations here.

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.

Obituary

If any significant core contributor has died, we've added a short obituary here.

Acknowledgements

The list of people to thank goes here.

Reporting Bugs

This doesn't usually need to be changed from the previous perldelta.

SEE ALSO

This doesn't usually need to be changed from the previous perldelta.