Updated perlfaq to CPAN version 5.0150040
[perl.git] / Porting / git-deltatool
1 #!/usr/bin/perl
2 #
3 # This is a rough draft of a tool to aid in generating a perldelta file
4 # from a series of git commits.
5
6 use 5.010;
7 use strict;
8 use warnings;
9 package Git::DeltaTool;
10
11 use Class::Struct;
12 use File::Basename;
13 use File::Temp;
14 use Getopt::Long;
15 use Git::Wrapper;
16 use Term::ReadKey;
17 use Term::ANSIColor;
18 use Pod::Usage;
19
20 BEGIN { struct( git => '$', last_tag => '$', opt => '%', original_stdout => '$' ) }
21
22 __PACKAGE__->run;
23
24 #--------------------------------------------------------------------------#
25 # main program
26 #--------------------------------------------------------------------------#
27
28 sub run {
29   my $class = shift;
30
31   my %opt = (
32     mode => 'assign',
33   );
34
35   GetOptions( \%opt,
36     # inputs
37     'mode|m:s', # 'assign', 'review', 'render', 'update'
38     'type|t:s', # select by status
39     'status|s:s', # status to set for 'update'
40     'since:s', # origin commit
41     'help|h',  # help
42   );
43
44   pod2usage() if $opt{help};
45
46   my $git = Git::Wrapper->new(".");
47   my $git_id = $opt{since};
48   if ( defined $git_id ) {
49     die "Invalid git identifier '$git_id'\n"
50       unless eval { $git->show($git_id); 1 };
51   } else {
52     ($git_id) = $git->describe;
53     $git_id =~ s/-.*$//;
54   }
55   my $gdt = $class->new( git => $git, last_tag => $git_id, opt => \%opt );
56
57   if ( $opt{mode} eq 'assign' ) {
58     $opt{type} //= 'new';
59     $gdt->assign;
60   }
61   elsif ( $opt{mode} eq 'review' ) {
62     $opt{type} //= 'pending';
63     $gdt->review;
64   }
65   elsif ( $opt{mode} eq 'render' ) {
66     $opt{type} //= 'pending';
67     $gdt->render;
68   }
69   elsif ( $opt{mode} eq 'summary' ) {
70     $opt{type} //= 'pending';
71     $gdt->summary;
72   }
73   elsif ( $opt{mode} eq 'update' ) {
74     die "Explicit --type argument required for update mode\n"
75       unless defined $opt{type};
76     die "Explicit --status argument required for update mode\n"
77       unless defined $opt{status};
78     $gdt->update;
79   }
80   else {
81     die "Unrecognized mode '$opt{mode}'\n";
82   }
83   exit 0;
84 }
85
86 #--------------------------------------------------------------------------#
87 # program modes (and iterator)
88 #--------------------------------------------------------------------------#
89
90 sub assign {
91   my ($self) = @_;
92   my @choices = ( $self->section_choices, $self->action_choices );
93   $self->_iterate_commits(
94     sub {
95       my ($log, $i, $count) = @_;
96       say "\n### Commit @{[$i+1]} of $count ###";
97       say "-" x 75;
98       $self->show_header($log);
99       $self->show_body($log, 1);
100       say "-" x 75;
101       return $self->dispatch( $self->prompt( @choices ), $log);
102     }
103   );
104   return;
105 }
106
107 sub review {
108   my ($self) = @_;
109   my @choices = ( $self->review_choices, $self->action_choices );
110   $self->_iterate_commits(
111     sub {
112       my ($log, $i, $count) = @_;
113       say "\n### Commit @{[$i+1]} of $count ###";
114       say "-" x 75;
115       $self->show_header($log);
116       $self->show_notes($log, 1);
117       say "-" x 75;
118       return $self->dispatch( $self->prompt( @choices ), $log);
119     }
120   );
121   return;
122 }
123
124 sub render {
125   my ($self) = @_;
126   my %sections;
127   $self->_iterate_commits(
128     sub {
129       my $log = shift;
130       my $section = $self->note_section($log) or return;
131       push @{ $sections{$section} }, $self->note_delta($log);
132       return 1;
133     }
134   );
135   my @order = $self->section_order;
136   my %known = map { $_ => 1 } @order;
137   my @rest = grep { ! $known{$_} } keys %sections;
138   for my $s ( @order, @rest ) {
139     next unless ref $sections{$s};
140     say "-"x75;
141     say uc($s) . "\n";
142     say join ( "\n", @{ $sections{$s} }, "" );
143   }
144   return;
145 }
146
147 sub summary {
148   my ($self) = @_;
149   $self->_iterate_commits(
150     sub {
151       my $log = shift;
152       $self->show_header($log);
153       return 1;
154     }
155   );
156   return;
157 }
158
159 sub update {
160   my ($self) = @_;
161
162   my $status = $self->opt('status')
163     or die "The 'status' option must be supplied for update mode\n";
164
165   $self->_iterate_commits(
166     sub {
167       my $log = shift;
168       my $note = $log->notes;
169       $note =~ s{^(perldelta.*\[)\w+(\].*)}{$1$status$2}ms;
170       $self->add_note( $log->id, $note );
171       return 1;
172     }
173   );
174   return;
175 }
176
177 sub _iterate_commits {
178   my ($self, $fcn) = @_;
179   my $type = $self->opt('type');
180   say STDERR "Scanning for $type commits since " . $self->last_tag . "...";
181   my $list = [ $self->find_commits($type) ];
182   my $count = @$list;
183   while ( my ($i,$log) = each @$list ) {
184     redo unless $fcn->($log, $i, $count);
185   }
186   return 1;
187 }
188
189 #--------------------------------------------------------------------------#
190 # methods
191 #--------------------------------------------------------------------------#
192
193 sub add_note {
194   my ($self, $id, $note) = @_;
195   my @lines = split "\n", _strip_comments($note);
196   pop @lines while @lines && $lines[-1] =~ m{^\s*$};
197   my $tempfh = File::Temp->new;
198   if (@lines) {
199     $tempfh->printflush( join( "\n", @lines), "\n" );
200     $self->git->notes('edit', '-F', "$tempfh", $id);
201   }
202   else {
203     $tempfh->printflush( "\n" );
204     # git notes won't take an empty file as input
205     system("git notes edit -F $tempfh $id");
206   }
207
208   return;
209 }
210
211 sub dispatch {
212   my ($self, $choice, $log) = @_;
213   return unless $choice;
214   my $method = "do_$choice->{handler}";
215   return 1 unless $self->can($method); # missing methods "succeed"
216   return $self->$method($choice, $log);
217 }
218
219 sub edit_text {
220   my ($self, $text, $args) = @_;
221   $args //= {};
222   my $tempfh = File::Temp->new;
223   $tempfh->printflush( $text );
224   if ( my @editor = split /\s+/, ($ENV{VISUAL} || $ENV{EDITOR}) ) {
225     push @editor, "-f" if $editor[0] =~ /^gvim/;
226     system(@editor, "$tempfh");
227   }
228   else {
229     warn("No VISUAL or EDITOR defined");
230   }
231   $tempfh->seek(0,0);
232   return do { local $/; <$tempfh> };
233 }
234
235 sub find_commits {
236   my ($self, $type) = @_;
237   $type //= 'new';
238   my @commits = $self->git->log($self->last_tag . "..HEAD");
239   $_ = Git::Wrapper::XLog->from_log($_) for @commits;
240   my @list;
241   if ( $type eq 'new' ) {
242     @list = grep { ! $_->notes } @commits;
243   }
244   else {
245     @list = grep { $self->note_status( $_ ) eq $type } @commits;
246   }
247   return @list;
248 }
249
250 sub get_diff {
251   my ($self, $log) = @_;
252   my @diff = $self->git->show({ stat => 1, p => 1 }, $log->id);
253   return join("\n", @diff);
254 }
255
256 sub note_delta {
257   my ($self, $log) = @_;
258   my @delta = split "\n", ($log->notes || '');
259   return '' unless @delta;
260   splice @delta, 0, 2;
261   return join( "\n", @delta, "" );
262 }
263
264 sub note_section {
265   my ($self, $log) = @_;
266   my $note = $log->notes or return '';
267   my ($section) = $note =~ m{^perldelta:\s*([^\[]*)\s+}ms;
268   return $section || '';
269 }
270
271 sub note_status {
272   my ($self, $log) = @_;
273   my $note = $log->notes or return '';
274   my ($status) = $note =~ m{^perldelta:\s*[^\[]*\[(\w+)\]}ms;
275   return $status || '';
276 }
277
278 sub note_template {
279   my ($self, $log, $text) = @_;
280   my $diff = _prepend_comment( $self->get_diff($log) );
281   return << "HERE";
282 # Edit commit note below. Do not change the first line. Comments are stripped
283 $text
284
285 $diff
286 HERE
287 }
288
289 sub prompt {
290   my ($self, @choices) = @_;
291   my ($valid, @menu, %keymap) = '';
292   for my $c ( map { @$_ } @choices ) {
293     my ($item) = grep { /\(/ } split q{ }, $c->{name};
294     my ($button) = $item =~ m{\((.)\)};
295     die "No key shortcut found for '$item'" unless $button;
296     die "Duplicate key shortcut found for '$item'" if $keymap{lc $button};
297     push @menu, $item;
298     $valid .= lc $button;
299     $keymap{lc $button} = $c;
300   }
301   my $keypress = $self->prompt_key( $self->wrap_list(@menu), $valid );
302   return $keymap{lc $keypress};
303 }
304
305 sub prompt_key {
306   my ($self, $prompt, $valid_keys) = @_;
307   my $key;
308   KEY: {
309     say $prompt;
310     ReadMode 3;
311     $key = lc ReadKey(0);
312     ReadMode 0;
313     if ( $key !~ qr/\A[$valid_keys]\z/i ) {
314       say "";
315       redo KEY;
316     }
317   }
318   return $key;
319 }
320
321 sub show_body {
322   my ($self, $log, $lf) = @_;
323   return unless my $body = $log->body;
324   say $lf ? "\n$body" : $body;
325   return;
326 }
327
328 sub show_header {
329   my ($self, $log) = @_;
330   my $header = $log->short_id;
331   $header .= " " . $log->subject if length $log->subject;
332   $header .= sprintf(' (%s)', $log->author) if $log->author;
333   say colored( $header, "yellow");
334   return;
335 }
336
337 sub show_notes {
338   my ($self, $log, $lf) = @_;
339   return unless my $notes = $log->notes;
340   say $lf ? "\n$notes" : $notes;
341   return;
342 }
343
344 sub wrap_list {
345   my ($self, @list) = @_;
346   my $line = shift @list;
347   my @wrap;
348   for my $item ( @list ) {
349     if ( length( $line . $item ) > 70 ) {
350       push @wrap, $line;
351       $line = $item ne $list[-1] ? $item : "or $item";
352     }
353     else {
354       $line .= $item ne $list[-1] ? ", $item" : " or $item";
355     }
356   }
357   return join("\n", @wrap, $line);
358 }
359
360 sub y_n {
361   my ($self, $msg) = @_;
362   my $key = $self->prompt_key($msg . " (y/n?)", 'yn');
363   return $key eq 'y';
364 }
365
366 #--------------------------------------------------------------------------#
367 # handlers
368 #--------------------------------------------------------------------------#
369
370 sub do_blocking {
371   my ($self, $choice, $log) = @_;
372   my $note = "perldelta: Unknown [blocking]\n";
373   $self->add_note( $log->id, $note );
374   return 1;
375 }
376
377 sub do_examine {
378   my ($self, $choice, $log) = @_;
379   $self->start_pager;
380   say $self->get_diff($log);
381   $self->end_pager;
382   return;
383 }
384
385 sub do_cherry {
386   my ($self, $choice, $log) = @_;
387   my $id = $log->short_id;
388   $self->y_n("Recommend a cherry pick of '$id' to maint?") or return;
389   my $cherrymaint = dirname($0) . "/cherrymaint";
390   system("$^X $cherrymaint --vote $id");
391   return; # false will re-prompt the same commit
392 }
393
394 sub do_done {
395   my ($self, $choice, $log) = @_;
396   my $note = $log->notes;
397   $note =~ s{^(perldelta.*\[)\w+(\].*)}{$1done$2}ms;
398   $self->add_note( $log->id, $note );
399   return 1;
400 }
401
402 sub do_edit {
403   my ($self, $choice, $log) = @_;
404   my $old_note = $log->notes;
405   my $new_note = $self->edit_text( $self->note_template( $log, $old_note) );
406   $self->add_note( $log->id, $new_note );
407   return 1;
408 }
409
410 sub do_head2 {
411   my ($self, $choice, $log) = @_;
412   my $section = _strip_parens($choice->{name});
413   my $subject = $log->subject;
414   my $body = $log->body;
415
416   my $template = $self->note_template( $log,
417     "perldelta: $section [pending]\n\n=head2 $subject\n\n$body\n"
418   );
419
420   my $note = $self->edit_text( $template );
421   if ( ($note ne $template) or $self->y_n("Note unchanged. Commit it?") ) {
422     $self->add_note( $log->id, $note );
423     return 1;
424   }
425   return;
426 }
427
428 sub do_linked_item {
429   my ($self, $choice, $log) = @_;
430   my $section = _strip_parens($choice->{name});
431   my $subject = $log->subject;
432   my $body = $log->body;
433
434   my $template = $self->note_template( $log,
435     "perldelta: $section [pending]\n\n=head3 L<LINK>\n\n=over\n\n=item *\n\n$subject\n\n$body\n\n=back\n"
436   );
437
438   my $note = $self->edit_text($template);
439   if ( ($note ne $template) or $self->y_n("Note unchanged. Commit it?") ) {
440     $self->add_note( $log->id, $note );
441     return 1;
442   }
443   return;
444 }
445
446 sub do_item {
447   my ($self, $choice, $log) = @_;
448   my $section = _strip_parens($choice->{name});
449   my $subject = $log->subject;
450   my $body = $log->body;
451
452   my $template = $self->note_template( $log,
453     "perldelta: $section [pending]\n\n=item *\n\n$subject\n\n$body\n"
454   );
455
456   my $note = $self->edit_text($template);
457   if ( ($note ne $template) or $self->y_n("Note unchanged. Commit it?") ) {
458     $self->add_note( $log->id, $note );
459     return 1;
460   }
461   return;
462 }
463
464 sub do_none {
465   my ($self, $choice, $log) = @_;
466   my $note = "perldelta: None [ignored]\n";
467   $self->add_note( $log->id, $note );
468   return 1;
469 }
470
471 sub do_platform {
472   my ($self, $choice, $log) = @_;
473   my $section = _strip_parens($choice->{name});
474   my $subject = $log->subject;
475   my $body = $log->body;
476
477   my $template = $self->note_template( $log,
478     "perldelta: $section [pending]\n\n=item PLATFORM-NAME\n\n$subject\n\n$body\n"
479   );
480
481   my $note = $self->edit_text($template);
482   if ( ($note ne $template) or $self->y_n("Note unchanged. Commit it?") ) {
483     $self->add_note( $log->id, $note );
484     return 1;
485   }
486   return;
487 }
488
489 sub do_quit { exit 0 }
490
491 sub do_repeat { return 0 }
492
493 sub do_skip { return 1 }
494
495 sub do_special {
496   my ($self, $choice, $log) = @_;
497   my $section = _strip_parens($choice->{name});
498   my $subject = $log->subject;
499   my $body = $log->body;
500
501   my $template = $self->note_template( $log, << "HERE" );
502 perldelta: $section [pending]
503
504 $subject
505
506 $body
507 HERE
508
509   my $note = $self->edit_text( $template );
510   if ( ($note ne $template) or $self->y_n("Note unchanged. Commit it?") ) {
511     $self->add_note( $log->id, $note );
512     return 1;
513   }
514   return;
515 }
516
517 sub do_subsection {
518   my ($self, $choice, $log) = @_;
519   my @choices = ( $choice->{subsection}, $self->submenu_choices );
520   say "For " . _strip_parens($choice->{name}) . ":";
521   return $self->dispatch( $self->prompt( @choices ), $log);
522 }
523
524 #--------------------------------------------------------------------------#
525 # define prompts
526 #--------------------------------------------------------------------------#
527
528 sub action_choices {
529   my ($self) = @_;
530   state $action_choices = [
531       { name => 'E(x)amine', handler => 'examine' },
532       { name => '(+)Cherrymaint', handler => 'cherry' },
533       { name => '(?)NeedHelp', handler => 'blocking' },
534       { name => 'S(k)ip', handler => 'skip' },
535       { name => '(Q)uit', handler => 'quit' },
536   ];
537   return $action_choices;
538 }
539
540 sub submenu_choices {
541   my ($self) = @_;
542   state $submenu_choices = [
543       { name => '(B)ack', handler => 'repeat' },
544   ];
545   return $submenu_choices;
546 }
547
548
549 sub review_choices {
550   my ($self) = @_;
551   state $action_choices = [
552       { name => '(E)dit', handler => 'edit' },
553       { name => '(I)gnore', handler => 'none' },
554       { name => '(D)one', handler => 'done' },
555   ];
556   return $action_choices;
557 }
558
559 sub section_choices {
560   my ($self, $key) = @_;
561   state $section_choices = [
562     # Headline stuff that should go first
563     {
564       name => 'Core (E)nhancements',
565       handler => 'head2',
566     },
567     {
568       name => 'Securit(y)',
569       handler => 'head2',
570     },
571     {
572       name => '(I)ncompatible Changes',
573       handler => 'head2',
574     },
575     {
576       name => 'Dep(r)ecations',
577       handler => 'head2',
578     },
579     {
580       name => '(P)erformance Enhancements',
581       handler => 'item',
582     },
583
584     # Details on things installed with Perl (for Perl developers)
585     {
586       name => '(M)odules and Pragmata',
587       handler => 'subsection',
588       subsection => [
589         {
590           name => '(N)ew Modules and Pragmata',
591           handler => 'item',
592         },
593         {
594           name => '(U)pdated Modules and Pragmata',
595           handler => 'item',
596         },
597         {
598           name => '(R)emoved Modules and Pragmata',
599           handler => 'item',
600         },
601       ],
602     },
603     {
604       name => '(D)ocumentation',
605       handler => 'subsection',
606       subsection => [
607         {
608           name => '(N)ew Documentation',
609           handler => 'linked_item',
610         },
611         {
612           name => '(C)hanges to Existing Documentation',
613           handler => 'linked_item',
614         },
615       ],
616     },
617     {
618       name => 'Dia(g)nostics',
619       handler => 'subsection',
620       subsection => [
621         {
622           name => '(N)ew Diagnostics',
623           handler => 'item',
624         },
625         {
626           name => '(C)hanges to Existing Diagnostics',
627           handler => 'item',
628         },
629       ],
630     },
631     {
632       name => '(U)tilities',
633       handler => 'linked_item',
634     },
635
636     # Details on building/testing Perl (for porters and packagers)
637     {
638       name => '(C)onfiguration and Compilation',
639       handler => 'item',
640     },
641     {
642       name => '(T)esting', # new tests or significant notes about it
643       handler => 'item',
644     },
645     {
646       name => 'Pl(a)tform Support',
647       handler => 'subsection',
648       subsection => [
649         {
650           name => '(N)ew Platforms',
651           handler => 'platform',
652         },
653         {
654           name => '(D)iscontinued Platforms',
655           handler => 'platform',
656         },
657         {
658           name => '(P)latform-Specific Notes',
659           handler => 'platform',
660         },
661       ],
662     },
663
664     # Details on perl internals (for porters and XS developers)
665     {
666       name => 'Inter(n)al Changes',
667       handler => 'item',
668     },
669
670     # Bugs fixed and related stuff
671     {
672       name => 'Selected Bug (F)ixes',
673       handler => 'item',
674     },
675     {
676       name => 'Known Prob(l)ems',
677       handler => 'item',
678     },
679
680     # dummy options for special handling
681     {
682       name => '(S)pecial',
683       handler => 'special',
684     },
685     {
686       name => '(*)None',
687       handler => 'none',
688     },
689   ];
690   return $section_choices;
691 }
692
693 sub section_order {
694   my ($self) = @_;
695   state @order;
696   if ( ! @order ) {
697     for my $c ( @{ $self->section_choices } ) {
698       if ( $c->{subsection} ) {
699         push @order, map { $_->{name} } @{$c->{subsection}};
700       }
701       else {
702         push @order, $c->{name};
703       }
704     }
705   }
706   return @order;
707 }
708
709 #--------------------------------------------------------------------------#
710 # Pager handling
711 #--------------------------------------------------------------------------#
712
713 sub get_pager { $ENV{'PAGER'} || `which less` || `which more` }
714
715 sub in_pager { shift->original_stdout ? 1 : 0 }
716
717 sub start_pager {
718   my $self = shift;
719   my $content = shift;
720   if (!$self->in_pager) {
721     local $ENV{'LESS'} ||= '-FXe';
722     local $ENV{'MORE'};
723     $ENV{'MORE'} ||= '-FXe' unless $^O =~ /^MSWin/;
724
725     my $pager = $self->get_pager;
726     return unless $pager;
727     open (my $cmd, "|-", $pager) || return;
728     $|++;
729     $self->original_stdout(*STDOUT);
730
731     # $pager will be closed once we restore STDOUT to $original_stdout
732     *STDOUT = $cmd;
733   }
734 }
735
736 sub end_pager {
737   my $self = shift;
738   return unless ($self->in_pager);
739   *STDOUT = $self->original_stdout;
740
741   # closes the pager
742   $self->original_stdout(undef);
743 }
744
745 #--------------------------------------------------------------------------#
746 # Utility functions
747 #--------------------------------------------------------------------------#
748
749 sub _strip_parens {
750   my ($name) = @_;
751   $name =~ s/[()]//g;
752   return $name;
753 }
754
755 sub _prepend_comment {
756   my ($text) = @_;
757   return join ("\n", map { s/^/# /g; $_ } split "\n", $text);
758 }
759
760 sub _strip_comments {
761   my ($text) = @_;
762   return join ("\n", grep { ! /^#/ } split "\n", $text);
763 }
764
765 #--------------------------------------------------------------------------#
766 # Extend Git::Wrapper::Log
767 #--------------------------------------------------------------------------#
768
769 package Git::Wrapper::XLog;
770 BEGIN { our @ISA = qw/Git::Wrapper::Log/; }
771
772 sub subject { shift->attr->{subject} }
773 sub body { shift->attr->{body} }
774 sub short_id { shift->attr->{short_id} }
775 sub author { shift->attr->{author} }
776
777 sub from_log {
778   my ($class, $log) = @_;
779
780   my $msg = $log->message;
781   my ($subject, $body) = $msg =~ m{^([^\n]+)\n*(.*)}ms;
782   $subject //= '';
783   $body //= '';
784   $body =~ s/[\r\n]*\z//ms;
785
786   my ($short) = Git::Wrapper->new(".")->rev_parse({short => 1}, $log->id);
787
788   $log->attr->{subject} = $subject;
789   $log->attr->{body} = $body;
790   $log->attr->{short_id} = $short;
791   return bless $log, $class;
792 }
793
794 sub notes {
795   my ($self) = @_;
796   my @notes = eval { Git::Wrapper->new(".")->notes('show', $self->id) };
797   pop @notes while @notes && $notes[-1] =~ m{^\s*$};
798   return unless @notes;
799   return join ("\n", @notes);
800 }
801
802 __END__
803
804 =head1 NAME
805
806 git-deltatool - Annotate commits for perldelta
807
808 =head1 SYNOPSIS
809
810  # annotate commits back to last 'git describe' tag
811
812  $ git-deltatool
813
814  # review annotations
815
816  $ git-deltatool --mode review
817
818  # review commits needing help
819
820  $ git-deltatool --mode review --type blocking
821
822  # summarize commits needing help
823
824  $ git-deltatool --mode summary --type blocking
825
826  # assemble annotations by section to STDOUT
827
828  $ git-deltatool --mode render
829
830  # Get a list of commits needing further review, e.g. for peer review
831
832  $ git-deltatool --mode summary --type blocking
833
834  # mark 'pending' annotations as 'done' (i.e. added to perldelta)
835
836  $ git-deltatool --mode update --type pending --status done
837
838 =head1 OPTIONS
839
840 =over
841
842 =item B<--mode>|B<-m> MODE
843
844 Indicates the run mode for the program.  The default is 'assign' which
845 assigns categories and marks the notes as 'pending' (or 'ignored').  Other
846 modes are 'review', 'render', 'summary' and 'update'.
847
848 =item B<--type>|B<-t> TYPE
849
850 Indicates what types of commits to process.  The default for 'assign' mode is
851 'new', which processes commits without any perldelta notes.  The default for
852 'review', 'summary' and 'render' modes is 'pending'.  The options must be set
853 explicitly for 'update' mode.
854
855 The type 'blocking' is reserved for commits needing further review.
856
857 =item B<--status>|B<-s> STATUS
858
859 For 'update' mode only, sets a new status.  While there is no restriction,
860 it should be one of 'new', 'pending', 'blocking', 'ignored' or 'done'.
861
862 =item B<--since> REVISION
863
864 Defines the boundary for searching git commits.  Defaults to the last
865 major tag (as would be given by 'git describe').
866
867 =item B<--help>
868
869 Shows the manual.
870
871 =back
872
873 =head1 TODO
874
875 It would be nice to make some of the structured sections smarter -- e.g.
876 look at changed files in pod/* for Documentation section entries.  Likewise
877 it would be nice to collate them during the render phase -- e.g. cluster
878 all platform-specific things properly.
879
880 =head1 AUTHOR
881
882 David Golden <dagolden@cpan.org>
883
884 =head1 COPYRIGHT AND LICENSE
885
886 This software is copyright (c) 2010 by David Golden.
887
888 This is free software; you can redistribute it and/or modify it under the same
889 terms as the Perl 5 programming language system itself.
890
891 =cut
892