handle JSON meta files on CPAN

[perl5.git] / Porting / how_to_write_a_perldelta.pod

diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod
index 7ce86d2..5c2d88c 100644 (file)
--- a/Porting/how_to_write_a_perldelta.pod
+++ b/Porting/how_to_write_a_perldelta.pod
@@ -3,12 +3,12 @@
 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.
 
@@ -37,8 +37,13 @@ Be consistent in how bugs are referenced. One style is
 
 =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
 
@@ -132,13 +137,23 @@ 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 this section following a template like this:
+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
 
-That's a start and the output can be copied/inserted into the perldelta.
+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
@@ -261,47 +276,9 @@ 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
+Autogenerate this section by running something like this:
 
-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
 
@@ -326,15 +303,9 @@ here.
 
 =item Acknowledgements
 
-The list of people to thank goes here.
-
-You can find the list of committers and authors by:
-
-  % git log v5.11.1..HEAD | perl -nlwe '$seen{$1}++ if /^Author: ([^<]*)/; END { print for sort keys %seen }'
-
-And how many files where changed by:
+Generate this with:
 
-  % git diff v5.11.1..HEAD | diffstat
+  perl Porting/acknowledgements.pl v5.15.0..HEAD
 
 =item Reporting Bugs