sync lib/Module/Build/Changes with CPAN equivalent

[p5sagit/p5-mst-13.2.git] / Porting / how_to_write_a_perldelta.pod

=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 summarised 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