| 1 |
NAME |
| 2 |
|
| 3 |
Dist::Zilla::Plugin::ChangelogFromGit - Write a Changes file from a |
| 4 |
project's git log. |
| 5 |
|
| 6 |
VERSION |
| 7 |
|
| 8 |
version 0.017 |
| 9 |
|
| 10 |
SYNOPSIS |
| 11 |
|
| 12 |
Here's an example dist.ini section showing all the current options and |
| 13 |
their default values. |
| 14 |
|
| 15 |
[ChangelogFromGit] |
| 16 |
max_age = 365 |
| 17 |
tag_regexp = ^v(\d+\.\d+)$ |
| 18 |
file_name = CHANGES |
| 19 |
wrap_column = 74 |
| 20 |
debug = 0 |
| 21 |
|
| 22 |
Variables don't need to be set to their default values. This is |
| 23 |
equivalent to the configuration above. |
| 24 |
|
| 25 |
[ChangelogFromGit] |
| 26 |
|
| 27 |
DESCRIPTION |
| 28 |
|
| 29 |
This Dist::Zilla plugin turns a project's git commit log into a change |
| 30 |
log file. It's better than simply running `git log > CHANGES` in at |
| 31 |
least two ways. First, it understands release tags, and it uses them to |
| 32 |
group changes by release. Second, it reformats the changes to make them |
| 33 |
easier to read. And third, subclasses can change some or all of the |
| 34 |
reformatting to make change logs even easier to read. |
| 35 |
|
| 36 |
See this project's CHANGES file for sample output. Yes, this project |
| 37 |
uses itself to generate its own change log. Why not? |
| 38 |
|
| 39 |
CONFIGURATION / PUBLIC ATTRIBUTES |
| 40 |
|
| 41 |
As seen in the "SYNOPSIS", this plugin has a number of public |
| 42 |
attributes that may be set using dist.ini configuration variables. |
| 43 |
|
| 44 |
max_age = INTEGER |
| 45 |
|
| 46 |
The max_age configuration variable limits the age of releases to be |
| 47 |
included in the change log. The default is to include releases going |
| 48 |
back about a year. To include about two years, one would double the |
| 49 |
default value: |
| 50 |
|
| 51 |
[ChangelogFromGit] |
| 52 |
max_age = 730 |
| 53 |
|
| 54 |
max_age is intended to limit the size of change logs for large, |
| 55 |
long-term projects that don't want to include the entire, huge commit |
| 56 |
history in every release. |
| 57 |
|
| 58 |
min_releases = INTEGER |
| 59 |
|
| 60 |
min_releases sets the minimum number of releases that should be |
| 61 |
included. It defaults to 1 so that at least the current release is |
| 62 |
added, regardless of max_age. |
| 63 |
|
| 64 |
[ChangelogFromGit] |
| 65 |
min_releases = 5 |
| 66 |
|
| 67 |
max_releases = INTEGER |
| 68 |
|
| 69 |
c<max_releases> allows you limit the number of releases included. |
| 70 |
max_age will still be the limiting factor if it contains fewer releases |
| 71 |
than the max specified. |
| 72 |
|
| 73 |
[ChangelogFromGit] |
| 74 |
max_releases = 15 |
| 75 |
|
| 76 |
tag_regexp = REGULAR_EXPRESSION |
| 77 |
|
| 78 |
tag_regexp sets the regular expression that detects which tags mark |
| 79 |
releases. It also extracts the version numbers from these tags using a |
| 80 |
regular expression back reference or capture. For example, a project's |
| 81 |
release tags might match 'release-1.000', 'release-1.001', etc. This |
| 82 |
tag_regexp will find them and extract their versions. |
| 83 |
|
| 84 |
[ChangelogFromGit] |
| 85 |
tag_regexp = ^release-(\d+.*)$ |
| 86 |
|
| 87 |
There is no single standard format for release tags. tag_regexp |
| 88 |
defaults to the author's convention. It will most likely need to be |
| 89 |
changed. |
| 90 |
|
| 91 |
file_name = STRING |
| 92 |
|
| 93 |
file_name sets the name of the change log that will be written. It |
| 94 |
defaults to "CHANGES", but some people may prefer "Changes", |
| 95 |
"Changelog", or something else. |
| 96 |
|
| 97 |
[ChangelogFromGit] |
| 98 |
file_name = Changes |
| 99 |
|
| 100 |
wrap_column = INTEGER |
| 101 |
|
| 102 |
Different contributors tend to use different commit message formats, |
| 103 |
which can be disconcerting to the typographically aware release |
| 104 |
engineer. wrap_column sets the line length to which all commit messages |
| 105 |
will be re-wrapped. It's 74 columns by default. If this is too short: |
| 106 |
|
| 107 |
[ChangelogFromGit] |
| 108 |
wrap_column = 78 |
| 109 |
|
| 110 |
debug = BOOLEAN |
| 111 |
|
| 112 |
Developers are people, too. The debug option enables some noisy runtime |
| 113 |
tracing on STDERR. |
| 114 |
|
| 115 |
[ChangelogFromGit] |
| 116 |
debug = 1 |
| 117 |
|
| 118 |
exclude_message = REGULAR_EXPRESSION |
| 119 |
|
| 120 |
exclude_message sets a regular expression which discards matching |
| 121 |
commit messages. This provides a way to exclude commit messages such as |
| 122 |
'forgot to include file X' or 'typo'. The regular expression is case |
| 123 |
sensitive. |
| 124 |
|
| 125 |
[ChangelogFromGit] |
| 126 |
exclude_message = ^(forgot|typo) |
| 127 |
|
| 128 |
include_message can be used to do the opposite: exclude all changes |
| 129 |
except ones that match a regular expression. Using both at once is |
| 130 |
liable to generate empty change logs. |
| 131 |
|
| 132 |
include_message = REGULAR_EXPRESSION |
| 133 |
|
| 134 |
include_message does the opposite of exclude_message: it sets a regular |
| 135 |
expression which commit messages must match in order to be included in |
| 136 |
the Changes file. This means that when making a commit with a relevant |
| 137 |
message, you must include text that matches the regular expression |
| 138 |
pattern to have it included in the Changes file. All other commit |
| 139 |
messages are ignored. |
| 140 |
|
| 141 |
The regular expression is case sensitive. |
| 142 |
|
| 143 |
[ChangelogFromGit] |
| 144 |
include_message = ^Major |
| 145 |
|
| 146 |
Using both include_message and exclude_message at the same time will |
| 147 |
most likely result in empty change logs. |
| 148 |
|
| 149 |
HOW IT WORKS |
| 150 |
|
| 151 |
Dist::Zilla::ChangelogFromGit collects the tags matching tag_regexp |
| 152 |
that are not older than max_age days old. These are used to identify |
| 153 |
and time stamp releases. Each release is encapsulated into a |
| 154 |
Software::Release object. |
| 155 |
|
| 156 |
Git::Repository::Log::Iterator is used to collect the changes prior to |
| 157 |
each release but after the previous release. Change log entries are |
| 158 |
added to their respective Software::Release objects. |
| 159 |
|
| 160 |
$self->render_changelog() is called after all the relevant releases and |
| 161 |
changes are known. It must return the rendered change log as a string. |
| 162 |
That string will be used as the content for a |
| 163 |
Dist::Zilla::File::InMemory object representing the new change log. |
| 164 |
|
| 165 |
SUBCLASSING FOR NEW FORMATS |
| 166 |
|
| 167 |
Dist::Zilla::ChangelogFromGit implement about a dozen methods to render |
| 168 |
the various parts of a change log. Subclasses may override or augment |
| 169 |
any or all of these methods to alter the way change logs are rendered. |
| 170 |
|
| 171 |
All methods beginning with "render" return strings that will be |
| 172 |
incorporated into the change log. Methods that will not contribute to |
| 173 |
the change log must return empty strings. |
| 174 |
|
| 175 |
Rendering Entire Change Logs |
| 176 |
|
| 177 |
Methods beginning with "render_changelog" receive no parameters other |
| 178 |
than $self. Everything they need to know about the change log is |
| 179 |
included in the object's attributes: wrap_column, releases, |
| 180 |
skipped_release_count, earliest_date. |
| 181 |
|
| 182 |
render_changelog |
| 183 |
|
| 184 |
render_changelog() returns the text of the entire change log. By |
| 185 |
default, the change log is built from a header, zero or more releases, |
| 186 |
and a footer. |
| 187 |
|
| 188 |
sub render_changelog { |
| 189 |
my $self = shift(); |
| 190 |
return( |
| 191 |
$self->render_changelog_header() . |
| 192 |
$self->render_changelog_releases() . |
| 193 |
$self->render_changelog_footer() |
| 194 |
); |
| 195 |
} |
| 196 |
|
| 197 |
render_changelog_header |
| 198 |
|
| 199 |
render_changelog_header() renders some text that introduces the reader |
| 200 |
to the change log. |
| 201 |
|
| 202 |
sub render_changelog_header { |
| 203 |
my $self = shift(); |
| 204 |
my $header = ( |
| 205 |
"Changes from " . $self->format_datetime($self->earliest_date()) . |
| 206 |
" to present." |
| 207 |
); |
| 208 |
return $self->surround_line("=", $header) . "\n"; |
| 209 |
} |
| 210 |
|
| 211 |
render_changelog_releases |
| 212 |
|
| 213 |
render_changelog_releases() iterates through each release, calling upon |
| 214 |
$self to render them one at a time. |
| 215 |
|
| 216 |
sub render_changelog_releases { |
| 217 |
my $self = shift(); |
| 218 |
|
| 219 |
my $changelog = ''; |
| 220 |
|
| 221 |
RELEASE: foreach my $release (reverse $self->all_releases()) { |
| 222 |
next RELEASE if $release->has_no_changes(); |
| 223 |
$changelog .= $self->render_release($release); |
| 224 |
} |
| 225 |
|
| 226 |
return $changelog; |
| 227 |
} |
| 228 |
|
| 229 |
render_changelog_footer |
| 230 |
|
| 231 |
render_changelog_footer() tells the reader that the change log is over. |
| 232 |
Normally the end of the file is sufficient warning, but a truncated |
| 233 |
change log is friendlier when the reader knows what they're missing. |
| 234 |
|
| 235 |
sub render_changelog_footer { |
| 236 |
my $self = shift(); |
| 237 |
|
| 238 |
my $skipped_count = $self->skipped_release_count(); |
| 239 |
|
| 240 |
my $changelog_footer; |
| 241 |
|
| 242 |
if ($skipped_count) { |
| 243 |
my $releases = "release" . ($skipped_count == 1 ? "" : "s"); |
| 244 |
$changelog_footer = ( |
| 245 |
"Plus $skipped_count $releases after " . |
| 246 |
$self->format_datetime($self->earliest_date()) . '.' |
| 247 |
); |
| 248 |
} |
| 249 |
else { |
| 250 |
$changelog_footer = "End of releases."; |
| 251 |
} |
| 252 |
|
| 253 |
return $self->surround_line("=", $changelog_footer); |
| 254 |
} |
| 255 |
|
| 256 |
Rendering Individual Releases |
| 257 |
|
| 258 |
Methods beginning with "render_release" receive $self plus one |
| 259 |
additional parameter: a Software::Release object encapsulating the |
| 260 |
release and its changes. See Software::Release to learn the information |
| 261 |
that object encapsulates. |
| 262 |
|
| 263 |
render_release |
| 264 |
|
| 265 |
render_release() is called upon to render a single release. In the |
| 266 |
change log, a release consists of a header, one or more changes, and a |
| 267 |
footer. |
| 268 |
|
| 269 |
sub render_release { |
| 270 |
my ($self, $release) = @_; |
| 271 |
return( |
| 272 |
$self->render_release_header($release) . |
| 273 |
$self->render_release_changes($release) . |
| 274 |
$self->render_release_footer($release) |
| 275 |
); |
| 276 |
} |
| 277 |
|
| 278 |
render_release_header |
| 279 |
|
| 280 |
render_release_header() introduces a release. |
| 281 |
|
| 282 |
sub render_release_header { |
| 283 |
my ($self, $release) = @_; |
| 284 |
|
| 285 |
my $version = $release->version(); |
| 286 |
$version = $self->zilla()->version() if $version eq 'HEAD'; |
| 287 |
|
| 288 |
my $release_header = ( |
| 289 |
$self->format_release_tag($release->version()) . ' at ' . |
| 290 |
$self->format_datetime($release->date()) |
| 291 |
); |
| 292 |
|
| 293 |
return $self->surround_line("-", $release_header) . "\n"; |
| 294 |
} |
| 295 |
|
| 296 |
render_release_changes |
| 297 |
|
| 298 |
render_release_changes() iterates through the changes associated with |
| 299 |
each Software::Release object. It calls upon render_change() to render |
| 300 |
each change. |
| 301 |
|
| 302 |
sub render_release_changes { |
| 303 |
my ($self, $release) = @_; |
| 304 |
|
| 305 |
my $changelog = ''; |
| 306 |
|
| 307 |
foreach my $change (@{ $release->changes() }) { |
| 308 |
$changelog .= $self->render_change($release, $change); |
| 309 |
} |
| 310 |
|
| 311 |
return $changelog; |
| 312 |
} |
| 313 |
|
| 314 |
render_release_footer |
| 315 |
|
| 316 |
render_release_footer() may be used to divide releases. It's not used |
| 317 |
by default, but it's implemented for completeness. |
| 318 |
|
| 319 |
sub render_release_footer { |
| 320 |
my ($self, $release) = @_; |
| 321 |
return ''; |
| 322 |
} |
| 323 |
|
| 324 |
Rendering Individual Changes |
| 325 |
|
| 326 |
Methods beginning with "render_change" receive two parameters in |
| 327 |
addition to $self: a Software::Release object encapsulating the release |
| 328 |
containing this change, and a Software::Release::Change object |
| 329 |
encapsulating the change itself. |
| 330 |
|
| 331 |
render_change |
| 332 |
|
| 333 |
render_change() renders a single change, which is the catenation of a |
| 334 |
change header, change message, and footer. |
| 335 |
|
| 336 |
sub render_change { |
| 337 |
my ($self, $release, $change) = @_; |
| 338 |
return( |
| 339 |
$self->render_change_header($release, $change) . |
| 340 |
$self->render_change_message($release, $change) . |
| 341 |
$self->render_change_footer($release, $change) |
| 342 |
); |
| 343 |
} |
| 344 |
|
| 345 |
render_change_header |
| 346 |
|
| 347 |
render_change_header() generally renders identifying information about |
| 348 |
each change. This method's responsibility is to produce useful |
| 349 |
information in a pleasant format. |
| 350 |
|
| 351 |
sub render_change_header { |
| 352 |
my ($self, $release, $change) = @_; |
| 353 |
|
| 354 |
use Text::Wrap qw(fill); |
| 355 |
|
| 356 |
local $Text::Wrap::huge = 'wrap'; |
| 357 |
local $Text::Wrap::columns = $self->wrap_column(); |
| 358 |
|
| 359 |
my @indent = (" ", " "); |
| 360 |
|
| 361 |
return( |
| 362 |
fill( |
| 363 |
" ", " ", |
| 364 |
'Change: ' . $change->change_id |
| 365 |
) . |
| 366 |
"\n" . |
| 367 |
fill( |
| 368 |
" ", " ", |
| 369 |
'Author: ' . $change->author_name.' <'.$change->author_email.'>' |
| 370 |
) . |
| 371 |
"\n" . |
| 372 |
fill( |
| 373 |
" ", " ", |
| 374 |
'Date : ' . $self->format_datetime($change->date()) |
| 375 |
) . |
| 376 |
"\n\n" |
| 377 |
); |
| 378 |
} |
| 379 |
|
| 380 |
render_change_message |
| 381 |
|
| 382 |
render_change_message() renders the commit message for the change log. |
| 383 |
|
| 384 |
sub render_change_message { |
| 385 |
my ($self, $release, $change) = @_; |
| 386 |
|
| 387 |
use Text::Wrap qw(fill); |
| 388 |
|
| 389 |
return '' if $change->description() =~ /^\s/; |
| 390 |
|
| 391 |
local $Text::Wrap::huge = 'wrap'; |
| 392 |
local $Text::Wrap::columns = $self->wrap_column(); |
| 393 |
|
| 394 |
return fill(" ", " ", $change->description) . "\n"; |
| 395 |
} |
| 396 |
|
| 397 |
render_change_footer |
| 398 |
|
| 399 |
render_change_footer() returns summary and/or divider text for the |
| 400 |
change. |
| 401 |
|
| 402 |
sub render_change_footer { |
| 403 |
my ($self, $release, $change) = @_; |
| 404 |
return "\n"; |
| 405 |
} |
| 406 |
|
| 407 |
Formatting Data |
| 408 |
|
| 409 |
Dist::Zilla::Plugin::ChangelogFromGit includes a few methods to |
| 410 |
consistently format certain data types. |
| 411 |
|
| 412 |
format_datetime |
| 413 |
|
| 414 |
format_datetime() converts the DateTime objects used internally into |
| 415 |
friendly, human readable dates and times for the change log. |
| 416 |
|
| 417 |
sub format_datetime { |
| 418 |
my ($self, $datetime) = @_; |
| 419 |
return $datetime->strftime("%F %T %z"); |
| 420 |
} |
| 421 |
|
| 422 |
format_release_tag |
| 423 |
|
| 424 |
format_release_tag() turns potentially cryptic release tags into |
| 425 |
friendly version numbers for the change log. By default, it also |
| 426 |
replaces the 'HEAD' version with the current version being released. |
| 427 |
This accommodates release managers who prefer to tag their |
| 428 |
distributions after releasing them. |
| 429 |
|
| 430 |
sub format_release_tag { |
| 431 |
my ($self, $release_tag) = @_; |
| 432 |
|
| 433 |
return 'version ' . $self->zilla()->version() if $release_tag eq 'HEAD'; |
| 434 |
|
| 435 |
my $tag_regexp = $self->tag_regexp(); |
| 436 |
$release_tag =~ s/$tag_regexp/version $1/; |
| 437 |
return $release_tag; |
| 438 |
} |
| 439 |
|
| 440 |
surround_line |
| 441 |
|
| 442 |
surround_line() will surround a line of output with lines of dashes or |
| 443 |
other characters. It's used to help heading stand out. This method |
| 444 |
takes two strings: a character (or string) that will repeat to fill |
| 445 |
surrounding lines, and the line to surround. It returns a three-line |
| 446 |
string: the original line preceded and followed by surrounding lines. |
| 447 |
|
| 448 |
sub surround_line { |
| 449 |
my ($self, $character, $string) = @_; |
| 450 |
|
| 451 |
my $surrounder = substr( |
| 452 |
($character x (length($string) / length($character) + 1)), |
| 453 |
0, |
| 454 |
length($string) |
| 455 |
); |
| 456 |
|
| 457 |
return "$surrounder\n$string\n$surrounder\n"; |
| 458 |
} |
| 459 |
|
| 460 |
INTERNAL ATTRIBUTES |
| 461 |
|
| 462 |
Dist::Zilla::Plugin::ChangelogFromGit accumulates useful information |
| 463 |
into a few internal attributes. These aren't intended to be configured |
| 464 |
by dist.ini, but they are important for rendering change logs. |
| 465 |
|
| 466 |
earliest_date |
| 467 |
|
| 468 |
earliest_date() contains a DateTime object that represents the date and |
| 469 |
time of the earliest release to include. It's initialized as midnight |
| 470 |
for the date max_age() days ago. |
| 471 |
|
| 472 |
releases |
| 473 |
|
| 474 |
releases() contains an array reference of Software::Release objects |
| 475 |
that will be included in the change log. |
| 476 |
|
| 477 |
all_releases |
| 478 |
|
| 479 |
all_releases() returns a list of the Software::Release objects that |
| 480 |
should be included in the change log. It's a friendly equivalent of |
| 481 |
@{$self->releases()}. |
| 482 |
|
| 483 |
get_release |
| 484 |
|
| 485 |
get_release() returns a single release by index. The first release in |
| 486 |
the change log may be retrieved as $self->get_release(0). |
| 487 |
|
| 488 |
releae_count |
| 489 |
|
| 490 |
release_count() returns the number of Software::Release objects in the |
| 491 |
"releases" attribute. |
| 492 |
|
| 493 |
sort_releases |
| 494 |
|
| 495 |
sort_releases() sorts the Software::Release objects in the releases() |
| 496 |
using some comparator. For example, to sort releases in time order: |
| 497 |
|
| 498 |
$self->sort_releases( |
| 499 |
sub { |
| 500 |
DateTime->compare( $_[0]->date(), $_[1]->date() ) |
| 501 |
} |
| 502 |
); |
| 503 |
|
| 504 |
skipped_release_count |
| 505 |
|
| 506 |
skipped_release_count() contains the number of releases truncated by |
| 507 |
max_age(). The default render_changelog_footer() uses it to display the |
| 508 |
number of changes that have been omitted from the log. |
| 509 |
|
| 510 |
INTERNAL METHODS |
| 511 |
|
| 512 |
Dist::Zilla::Plugin::ChangelogFromGit implements a couple of |
| 513 |
"unpublished" methods. These are not intended for general use. |
| 514 |
|
| 515 |
gather_files() |
| 516 |
|
| 517 |
Find all release tags back to the earliest changelog date. |
| 518 |
|
| 519 |
Add a virtual release for the most recent change in the repository. |
| 520 |
This lets us include changes after the last releases, up to "HEAD". |
| 521 |
|
| 522 |
rungit() |
| 523 |
|
| 524 |
A wrapper to run git commands. |
| 525 |
|
| 526 |
Subversion and CVS |
| 527 |
|
| 528 |
This plugin is almost entirely a copy-and-paste port of a command-line |
| 529 |
tool I wrote a while ago. I also have tools to generate similar change |
| 530 |
logs for CVS and Subversion projects. I'm happy to contribute that code |
| 531 |
to people interested in creating Dist::Zilla plugins for other version |
| 532 |
control systems. |
| 533 |
|
| 534 |
We should also consider abstracting the formatting code out to a role |
| 535 |
so that it can be shared among different plugins. |
| 536 |
|
| 537 |
BUGS |
| 538 |
|
| 539 |
The documentation includes copies of the renderer methods. This |
| 540 |
increases technical debt, since changes to those methods must also be |
| 541 |
copied into the documentation. Rocco needs to finish Pod::Plexus and |
| 542 |
use it here to simplify maintenance of the documentation. |
| 543 |
|
| 544 |
Collecting all releases and changes before rendering the change log may |
| 545 |
be considered harmful for extremely large projects. If someone thinks |
| 546 |
they can generate change logs incrementally, their assistance would be |
| 547 |
appreciated. |
| 548 |
|
| 549 |
AUTHORS |
| 550 |
|
| 551 |
Rocco Caputo <[email protected]> - Initial release, and ongoing |
| 552 |
management and maintenance. |
| 553 |
|
| 554 |
Cory G. Watson <[email protected]> - Made formatting extensible and |
| 555 |
overridable. |
| 556 |
|
| 557 |
COPYRIGHT AND LICENSE |
| 558 |
|
| 559 |
This software is copyright (c) 2010-2018 by Rocco Caputo. |
| 560 |
|
| 561 |
This is free software; you may redistribute it and/or modify it under |
| 562 |
the same terms as the Perl 5 programming language itself. |
| 563 |
|