X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Fhow_to_write_a_perldelta.pod;h=66f7adcb2027c390146f327d11565c740f51eeca;hb=7b8f75d30d66734808d4913332e5ad001e9ce289;hp=dd8dac12f5fb0a216d51923831e2bc6e3ea5cddc;hpb=87b6d2691f69f385919a2dd70800297d8f5cd295;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod
index dd8dac1..66f7adc 100644
--- a/Porting/how_to_write_a_perldelta.pod
+++ b/Porting/how_to_write_a_perldelta.pod
@@ -6,6 +6,12 @@ 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 Template
+
+Note there is a file F<Porting/perldelta_template> which contains a
+skeleton version of a perldelta.pod file, which should normally be copied
+in at the start of a new release.
+
 =head2 Style
 
 Pod is more a physical markup language, rather than a logical markup language.
@@ -123,6 +129,43 @@ 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.
 
+B<FIXME> - this could be automated, although the two below would be easier
+to start with.
+
+Start with F<Porting/cmpVERSION.pl>
+
+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
+
+    =item *
+
+    C<less> upgraded from version 0.01 to 0.02
+
+That's a start.
+
+Once that's done, a more adventurous enhancement is 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
@@ -132,6 +175,61 @@ of these are built within the directories F<utils> and F<x2p>.
 
 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.
@@ -168,6 +266,48 @@ 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.
 
+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
+
+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
+
 =item Known Problems
 
 Descriptions of platform agnostic bugs we know we can't fix go here. Any