From 548e9a3a0c4e2b14151b17a2c96eedd7683fcc77 Mon Sep 17 00:00:00 2001 From: Leon Brocard Date: Thu, 14 Jul 2011 15:00:07 +0100 Subject: [PATCH] Add Porting/acknowledgements.pl to generate perldelta acknowledgements --- MANIFEST | 1 + Porting/acknowledgements.pl | 148 +++++++++++++++++++++++++++++++++++ Porting/how_to_write_a_perldelta.pod | 10 +-- Porting/perldelta_template.pod | 4 +- Porting/release_managers_guide.pod | 15 +--- pod/perldelta.pod | 4 +- t/porting/known_pod_issues.dat | 2 +- 7 files changed, 160 insertions(+), 24 deletions(-) create mode 100644 Porting/acknowledgements.pl diff --git a/MANIFEST b/MANIFEST index ac1fbc6..3037a49 100644 --- a/MANIFEST +++ b/MANIFEST @@ -4496,6 +4496,7 @@ pod/rofftoc Generate a table of contents in troff format pod/splitman Splits perlfunc into multiple man pages pod/splitpod Splits perlfunc into multiple pod pages Policy_sh.SH Hold site-wide preferences between Configure runs. +Porting/acknowledgements.pl Generate perldelta acknowledgements text Porting/add-package.pl Add/Update CPAN modules that are part of Core Porting/bump-perl-version bump the perl version in relevant files Porting/check83.pl Check whether we are 8.3-friendly diff --git a/Porting/acknowledgements.pl b/Porting/acknowledgements.pl new file mode 100644 index 0000000..bd9ac82 --- /dev/null +++ b/Porting/acknowledgements.pl @@ -0,0 +1,148 @@ +#!perl + +=head1 NAME + +Porting/acknowledgements.pl - Generate perldelta acknowledgements text + +=head1 SYNOPSIS + + perl Porting/acknowledgements.pl v5.15.0..HEAD + +=head1 DESCRIPTION + +This generates the text which goes in the Acknowledgements section in +a perldelta. You pass in the previous version and it guesses the next +version, fetches information from the repository and outputs the +text. + +=cut + +use strict; +use warnings; +use autodie; +use POSIX qw(ceil); +use Text::Wrap; +use Time::Piece; +use Time::Seconds; +use version; +$Text::Wrap::columns = 80; + +my $since_until = shift; + +my ( $since, $until ) = split '\.\.', $since_until; + +die "Usage: perl Porting/acknowledgements.pl v5.15.0..HEAD" + unless $since_until && $since && $until; + +my $previous_version = previous_version(); +my $next_version = next_version(); +my $development_time = development_time(); + +my ( $changes, $files ) = changes_files(); +my $formatted_changes = commify( round($changes) ); +my $formatted_files = commify( round($files) ); + +my $authors = authors(); +my $nauthors = $authors =~ tr/,/,/; +$nauthors++; + +my $text + = "Perl $next_version represents approximately $development_time of development +since Perl $previous_version and contains approximately $formatted_changes +lines of changes across $formatted_files files from $nauthors authors. + +Perl continues to flourish into its third decade thanks to a vibrant +community of users and developers. The following people are known to +have contributed the improvements that became Perl $next_version: + +$authors +The list above is almost certainly incomplete as it is automatically +generated from version control history. In particular, it does not +include the names of the (very much appreciated) contributors who +reported issues to the Perl bug tracker. + +Many of the changes included in this version originated in the CPAN +modules included in Perl's core. We're grateful to the entire CPAN +community for helping Perl to flourish. + +For a more complete list of all of Perl's historical contributors, +please see the F file in the Perl source distribution. +"; + +my $wrapped = fill( '', '', $text ); +print "$wrapped\n"; + +# return the previous Perl version, eg 5.15.0 +sub previous_version { + my $version = version->new($since); + $version =~ s/^v//; + return $version; +} + +# returns the upcoming release Perl version, eg 5.15.1 +sub next_version { + my $version = version->new($since); + ( $version->{version}->[-1] )++; + return version->new( join( '.', @{ $version->{version} } ) ); +} + +# returns the development time since the previous version in weeks +# or months +sub development_time { + my $dates = qx(git log --pretty=format:%ct --summary $since_until); + my $first_timestamp; + foreach my $line ( split $/, $dates ) { + next unless $line; + next unless $line =~ /^\d+$/; + $first_timestamp = $line; + } + + die "Missing first timestamp" unless $first_timestamp; + + my $now = localtime; + my $then = localtime($first_timestamp); + my $seconds = $now - $then; + my $weeks = ceil( $seconds / ONE_WEEK ); + my $months = ceil( $seconds / ONE_MONTH ); + + my $development_time; + if ( $months < 2 ) { + return "$weeks weeks"; + } else { + return "$months months"; + } +} + +# returns the number of changed lines and files since the previous +# version +sub changes_files { + my $output = qx(git diff --shortstat $since_until); + + # 585 files changed, 156329 insertions(+), 53586 deletions(-) + my ( $files, $insertions, $deletions ) + = $output + =~ /(\d+) files changed, (\d+) insertions\(\+\), (\d+) deletions\(-\)/; + my $changes = $insertions + $deletions; + return ( $changes, $files ); +} + +# rounds an integer to two significant figures +sub round { + my $int = shift; + my $length = length($int); + my $divisor = 10**( $length - 2 ); + return ceil( $int / $divisor ) * $divisor; +} + +# adds commas to a number at thousands, millions +sub commify { + local $_ = shift; + 1 while s/^([-+]?\d+)(\d{3})/$1,$2/; + return $_; +} + +# returns a list of the authors +sub authors { + return + qx(git log --pretty=fuller $since_until | $^X Porting/checkAUTHORS.pl --who -); +} diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod index 28389b9..5c2d88c 100644 --- a/Porting/how_to_write_a_perldelta.pod +++ b/Porting/how_to_write_a_perldelta.pod @@ -303,15 +303,9 @@ here. =item Acknowledgements -The list of people to thank goes here. +Generate this with: -You can find the list of committers and authors by: - - % git log --pretty='format:%an' v5.11.1..HEAD | sort | uniq - -And how many files where changed by: - - % git diff --stat=200,200 v5.11.1..HEAD + perl Porting/acknowledgements.pl v5.15.0..HEAD =item Reporting Bugs diff --git a/Porting/perldelta_template.pod b/Porting/perldelta_template.pod index 875ef33..65f9671 100644 --- a/Porting/perldelta_template.pod +++ b/Porting/perldelta_template.pod @@ -353,7 +353,9 @@ here. =head1 Acknowledgements -XXX The list of people to thank goes here. +Generate this with: + + perl Porting/acknowledgements.pl v5.15.0..HEAD =head1 Reporting Bugs diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod index 6c5f6a3..1525d32 100644 --- a/Porting/release_managers_guide.pod +++ b/Porting/release_managers_guide.pod @@ -361,20 +361,9 @@ part of I, do that now. =head3 finalize perldelta Finalize the perldelta. In particular, fill in the Acknowledgements -section. You can generate a list of contributors with checkAUTHORS.pl. -For example: +section, which can be generated with something like: - $ git log --pretty=fuller v5.13.${last}..HEAD | \ - perl Porting/checkAUTHORS.pl --who - - -Look at the previous L for how to write the opening -paragraph of the Acknowledgements section. To get the amount of -changed files and number of lines use this command: - - $ git diff --shortstat v5.15.0..HEAD | \ - ./perl -Ilib -nE 'my ($files, $insert, $delete) = /(\d+)/ga; say $insert + $delete, " lines of changes across $files files"' - -Making sure to round off the number of lines changed. + $ perl Porting/acknowledgements.pl v5.15.0..HEAD Re-read the perldelta to try to find any embarrassing typos and thinkos; remove any C or C flags; update the "Known Problems" section diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 2ac9848..d3bab27 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -726,7 +726,9 @@ here. =head1 Acknowledgements -XXX The list of people to thank goes here. +Generate this with: + + perl Porting/acknowledgements.pl v5.15.0..HEAD =head1 Reporting Bugs diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat index 26a4cca..1c02a98 100644 --- a/t/porting/known_pod_issues.dat +++ b/t/porting/known_pod_issues.dat @@ -309,7 +309,7 @@ porting/expand-macro.pl Verbatim line length including indents exceeds 80 by 2 porting/how_to_write_a_perldelta.pod There is no NAME 1 porting/how_to_write_a_perldelta.pod Verbatim line length including indents exceeds 80 by 3 porting/pumpkin.pod Verbatim line length including indents exceeds 80 by 9 -porting/release_managers_guide.pod Verbatim line length including indents exceeds 80 by 10 +porting/release_managers_guide.pod Verbatim line length including indents exceeds 80 by 9 porting/release_managers_guide.pod Verbatim paragraph in NAME section 1 porting/release_schedule.pod There is no NAME 1 symbian/perlutil.pod Verbatim line length including indents exceeds 80 by 4 -- 2.7.4