--- /dev/null
+=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<Stick to them>:
+
+=over 4
+
+=item * C<FE<lt>E<gt>> is for File
+
+=item * C<CE<lt>E<gt>> is for Code
+
+=item * C<LE<lt>E<gt>> is for Link
+
+=back
+
+Whilst modules could also be links, usually in the context of the perldelta
+the reference is to code C<use>ing them, rather than something within their
+documentation.
+
+Be consistent in how bugs are referenced. One style is
+
+=over 4
+
+=item rt.perl.org
+
+C<RT #43010> inline, but enclose in square brackets after a sentence.
+C<[RT #43010]>
+
+=item ActiveState
+
+C<http://bugs.activestate.com/show_bug.cgi?id=72443>
+
+=item Debian
+
+C<Debian bug #379463>
+
+=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<Notice> section in L<perl589delta>, 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</Performance Enhancements> section.
+
+Feature inside modules (pure-Perl and XS) go in L</Modules and Pragmata>
+
+=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 Modules and Pragmata
+
+All changes to installed files in F<ext/> and F<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
+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 to F<ext/> and F<lib/> by module, and then summarise all
+changes to a module as a group. This can be done by partitioning directories
+within F<ext/> and F<lib/> to a number of people.
+
+=item Utility Changes
+
+Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
+of these are built within the directories F<utils> and F<x2p>.
+
+=item New Documentation
+
+Changes which create B<new> files in F<pod/> go here.
+
+=item Changes to Existing Documentation
+
+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
+
+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<Configure>, F<installperl>, F<installman>, 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<ext/> and F<lib/> are best summarised in
+L</Modules and Pragmata>.
+
+=item New or Changed Diagnostics
+
+New or changed warnings emitted by the core's C<C> code go here.
+
+=item Changed Internals
+
+Changes which affect the interface available to C<XS> code go here.
+
+=item New Tests
+
+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
+may be.
+
+=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 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
projects / p5sagit/p5-mst-13.2.git / commitdiff