-=head1 How to write a perldelta
+=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
-do to do something, see if it's been done before, and if the approach works
+to do something, see if it's been done before, and if the approach works
there, steal it.
=head2 Template
-Note there is a file F<Porting/perldelta_template> which contains a
+Note there is a file F<Porting/perldelta_template.pod> which contains a
skeleton version of a perldelta.pod file, which should normally be copied
in at the start of a new release.
=item rt.perl.org
-C<RT #43010> inline, but enclose in square brackets after a sentence.
-C<[RT #43010]>
+C<perl #43010> inline, but enclose in square brackets after a sentence.
+C<[perl #43010]>. This mirrors how rt.perl.org subject lines appear.
+
+=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
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.
+B<FIXME> - this could be automated better
+
+If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
+will automatically print out several sections if relevant that can be
+pasted into F<perldelta>:
+
+ * New Modules and Pragmata
+ * Pragmata Changes
+ * Updated Modules
+ * 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, splice the extra lines right into the output,
+as a basis for summarising.
+
+(And if not, experiment with using F<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 F<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 F<pod/buildtoc> already does to
+splice into existing Makefiles on various platforms:
+
+http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498
+
+Perl is this really powerful language for text manipulation. And fun to
+play with. We need to get that message out. :-)
+
=item Utility Changes
Changes to installed programs such as F<perlbug> and F<xsubpp> go here. Most
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.
in F<t/> aren't worth summarising, 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 Known Problems
Descriptions of platform agnostic bugs we know we can't fix go here. Any
=item Acknowledgements
-The list of people to thank goes here.
+Generate this with:
+
+ perl Porting/acknowledgements.pl v5.15.0..HEAD
=item Reporting Bugs
https://perl5.git.perl.org / perl5.git / blobdiff