Debian Codegraph @

README

raw
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