-=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
-C<http://bugs.activestate.com/show_bug.cgi?id=72443>
+C<L<http://bugs.activestate.com/show_bug.cgi?id=72443>>
=item Debian
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.
+ 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.
+ This document describes differences between the 5.10.0 release
+ and the 5.12.0 release.
Clearly this sets the scope of which changes are to be summarised in the rest
of the document.
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.
+ There are no changes intentionally incompatible with 5.10.3.
+ If any exist, they are bugs and reports are welcome.
=item Core Enhancements
=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.
+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 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.
+collate changes by module, and then summarise 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>:
-B<FIXME> - this could be automated, although the two below would be easier
-to start with.
+ * New Modules and Pragmata
+ * Updated Modules and Pragmata
-Start with F<Porting/cmpVERSION.pl>
+(Currently, it does not update the Removed Modules and Pragmata section.)
-Augment it with a flag, so that instead of reporting which modules are
-different but have the same version, report on modules which I<are> different.
-Grab the old version from the exploded tarball, and the new version from
-the git checkout, and output the line
+Each section will have stub entries following a template like this:
- =item *
+ =item C<less>
- C<less> upgraded from version 0.01 to 0.02
+ Upgraded from version 0.01 to 0.02
-That's a start.
+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.
-Once that's done, a more adventurous enhancement is to automate grabbing
+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.
+a strict subset of the new one, use the extra lines 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. :-)
+for the particular file in core.)
=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>.
+of these are built within the directory F<utils>.
=item New Documentation
=over
-=item 1
+=item 1
Use F<git> to determine its Author
in F<t/> aren't worth summarising, although the bugs that they represent
may be.
-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!t/.*\.t!> (and I think also for new tests in
-F<ext/DynaLoader>)
-
-=item 4
-
-Diff them
-
-=item 5
+Autogenerate this section by running something like this:
-For each file only in the newer F<MANIFEST>
-
-=over
-
-=item 1
-
-Grab the description line from F<MANIFEST>
-
-=item 2
-
-Write out an =item section with the filename, and description, just like
-L<http://perl5.git.perl.org/perl.git/blob/maint-5.10:/pod/perl5101delta.pod>
-
-=back
-
-=back
+ # perl newtests-perldelta.pl v5.11.1 HEAD
=item Known Problems
=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