perl/Porting/how_to_write_a_perldelta.pod

=head1 NAME

how_to_write_a_perldelta - How to write a perldelta

=head2 Description

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. (L<perl5300delta> and L<perl5320delta> are both quite
lengthy and contain good examples for many of the perldelta sections.)

=head2 Template Automation

Note that F<Porting/perldelta_template.pod> contains a skeleton version of
a perldelta.pod file. Following the steps in the Release Manager's Guide
(F<Porting/release_managers_guide.pod>) usually ensures hassle-free
rotation of the most recently completed perldelta.pod and preparation of
a fresh new document ready for the next release.

The skeleton document also contains inline hints on how to prepare the
final perldelta.pod. (These hints should be removed in turn as each section
of the final perldelta.pod is completed.)

=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 common style, which is
expected by some commands given in the Release Manager's Guide, is as
follows:

=over 4

=item GitHub

C<[GH #12345]> can be used to reference both Issues and Pull Requests.

=item rt.cpan.org

C<rt.cpan.org #43010> inline, but enclose in square brackets after a sentence.
C<[rt.cpan.org #43010]>.  This mirrors how rt.cpan.org subject lines appear.

=item ActiveState

C<L<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. I<regex>
B<xor> I<regexp> - 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.10.0 release
    and the 5.12.0 release.

This clearly sets the scope of which changes are to be summarized in the
rest of the document.

For all releases, a second paragraph points to the previous perldelta:

    If you are upgrading from an earlier release such as 5.rXXX.aXXX,
    first read perl5XXXdelta, which describes differences between
    5.rXXX.aXXX and 5.sXXX.bXXX.

=item Notice

There was a I<Notice> section in L<perl589delta>, to carry an important
notice.

=item Core Enhancements

New core language features go here. Summarize 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 Security

Any security-related notices go here. In particular, any security
vulnerabilities closed should be noted here rather than in the
"Selected Bug Fixes" section.

L<perl5303delta> has multiple such examples, as well as
a useful accompanying paragraph outlining the known attack
vectors / requirements for the vulnerabilities to be exploitable.

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

Otherwise, changes should be listed as =head2 entries.

=item Deprecations

Add any new known deprecations (features, syntax, modules) here.

A I<Module removals> subsection can be used to foreshadow planned removal
of core modules in a future release. Modules that were actually removed
in this release should go in the "Modules and Pragmata" section.

=item Performance Enhancements

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

=item Modules and Pragmata

All changes to installed files in F<cpan/>, F<dist/>, 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 by module, and then summarize all changes to a module as a
group.

If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
will automatically update two sections in F<perldelta>:

    * New Modules and Pragmata
    * Updated Modules and Pragmata
    * Removed Modules and Pragmata

Each section will have stub entries following a template like this:

    =item C<less>

    Upgraded from version 0.01 to 0.02

It does not include modules listed in F<Porting/Maintainers.pl> under
C<_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, use the extra lines as a basis for summarizing.

(And if not, experiment with using F<git> to get the relevant part of changelog
for the particular file in core.)

=item New Documentation

Changes which create B<new> files in F<pod/> go here.

B<FIXME> - 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<MANIFEST> file of each

=item 3

Search for lines matching C<m!^pod/.*\.pod!>

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

=over

=item 1

Use F<git> 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<perlfoo>, by A. U. Thor, provides @description

=back

=back

=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 Diagnostics> or L</Changed Diagnostics>.

=item New Diagnostics

New warnings emitted by the core's C<C> code go here.

=item Changed Diagnostics

Changed warnings emitted by the core's C<C> code go here.

=item Utility Changes

Changes to installed programs such as F<perldoc> and F<xsubpp> go here. Most
of these are built within the directory F<utils>.

=item Configuration and Compilation

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

=item Testing

Changes which create B<new> files in F<t/> go here. Changes to existing files
in F<t/> aren't worth summarizing, 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 Platform Support

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 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 Discontinued Platforms

List any platforms that this version of perl no longer compiles on. The
reverse of the advice above applies - look for removed hints or README files.

=item Platform-Specific Notes

Changes of note to specific platforms go here.

=item Internal Changes

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

=item Selected Bug Fixes

Important bug fixes in the core language are summarized here.
Bug fixes in files in F<ext/> and F<lib/> are best summarized in
L</Modules and Pragmata>.

=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 Errata From Previous Releases

XXXXXXXXXX TODO

=item Obituary

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

=item Acknowledgements

Generate this with:

  perl Porting/acknowledgements.pl v5.15.0..HEAD

=item Reporting Bugs

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

=item Give Thanks

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