Dist/Zilla/PluginBundle/Starter.pm

filter: Statementstmt 100% 93 / 93 Branchbran 72.7% 16 / 22 Conditioncond 72.7% 8 / 11 MC/DCmcdc 33.3% 2 / 6 Subroutinesub 100% 43 / 43 Podpod 0.0% 0 / 8 totaltotal 88.5% 162 / 183 CC 19 SCAR 7.9
CC
19
Cov
93%
configure
7.1
pluginset_release_management
4.0
__ANON__
2.1
CRAP 2.2
↑ Summary Dist/Zilla/Starter.pm »
1 package Dist::Zilla::PluginBundle::Starter;
2  
3 11 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 11 with 'Dist::Zilla::Role::PluginBundle::Easy',
5 'Dist::Zilla::Role::PluginBundle::Config::Slicer',
6 'Dist::Zilla::Role::PluginBundle::PluginRemover';
7 11 ▶use namespace::clean;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 11 our $VERSION = 'v6.0.2';
10  
11 # Revisions can include entries with the standard plugin name, array ref of plugin/name/config,
12 # or coderefs which are passed the pluginbundle object and return a list of plugins in one of these formats.
13 my %revisions = (
14 1 => [
15 'GatherDir',
16 'MetaYAML',
17 'MetaJSON',
18 'License',
19 'ReadmeAnyFromPod',
20 'PodSyntaxTests',
21 'Test::ReportPrereqs',
22 ['Test::Compile' => { xt_mode => 1 }],
23 'MakeMaker',
24 'Manifest',
25 'PruneCruft',
26 'ManifestSkip',
27 'RunExtraTests',
28 'TestRelease',
29 'ConfirmRelease',
30 1 ▶ sub { $_[0]->pluginset_releaser },
Subroutine __ANON__: called CC=1 SCAR=0.0
31 'MetaConfig',
32 ['MetaNoIndex' => { directory => [qw(t xt inc share eg examples)] }],
33 'MetaProvides::Package',
34 'ShareDir',
35 'ExecDir',
36 ],
37 2 => [
38 'GatherDir',
39 'MetaYAML',
40 'MetaJSON',
41 'License',
42 'Pod2Readme',
43 'PodSyntaxTests',
44 'Test::ReportPrereqs',
45 ['Test::Compile' => { xt_mode => 1 }],
46 4 ▶ sub { $_[0]->pluginset_installer },
Subroutine __ANON__: called CC=1 SCAR=0.0
47 'Manifest',
48 'PruneCruft',
49 'ManifestSkip',
50 'RunExtraTests',
51 'TestRelease',
52 'ConfirmRelease',
53 4 ▶ sub { $_[0]->pluginset_releaser },
Subroutine __ANON__: called CC=1 SCAR=0.0
54 'MetaConfig',
55 ['MetaNoIndex' => { directory => [qw(t xt inc share eg examples)] }],
56 ['MetaProvides::Package' => { inherit_version => 0 }],
57 'ShareDir',
58 4 ▶ sub { $_[0]->pluginset_execdir },
Subroutine __ANON__: called CC=1 SCAR=0.0
59 ],
60 3 => [
61 1 ▶ sub { $_[0]->pluginset_gatherer },
Subroutine __ANON__: called CC=1 SCAR=0.0
62 'MetaYAML',
63 'MetaJSON',
64 'License',
65 'Pod2Readme',
66 'PodSyntaxTests',
67 'Test::ReportPrereqs',
68 ['Test::Compile' => { xt_mode => 1 }],
69 1 ▶ sub { $_[0]->pluginset_installer },
Subroutine __ANON__: called CC=1 SCAR=0.0
70 'Manifest',
71 'PruneCruft',
72 'ManifestSkip',
73 'RunExtraTests',
74 1 ▶ sub { $_[0]->pluginset_release_management }, # before test/confirm for before-release verification
Subroutine __ANON__: called CC=1 SCAR=0.0
75 'TestRelease',
76 'ConfirmRelease',
77 1 ▶ sub { $_[0]->pluginset_releaser },
Subroutine __ANON__: called CC=1 SCAR=0.0
78 'MetaConfig',
79 ['MetaNoIndex' => { directory => [qw(t xt inc share eg examples)] }],
80 1 ▶ sub { $_[0]->pluginset_metaprovides },
Subroutine __ANON__: called CC=1 SCAR=0.0
81 'ShareDir',
82 1 ▶ sub { $_[0]->pluginset_execdir },
Subroutine __ANON__: called CC=1 SCAR=0.0
83 ],
84 4 => [
85 1 ▶ sub { $_[0]->pluginset_gatherer },
Subroutine __ANON__: called CC=1 SCAR=0.0
86 'MetaYAML',
87 'MetaJSON',
88 'License',
89 'Pod2Readme',
90 'PodSyntaxTests',
91 'Test::ReportPrereqs',
92 ['Test::Compile' => { xt_mode => 1 }],
93 1 ▶ sub { $_[0]->pluginset_installer },
Subroutine __ANON__: called CC=1 SCAR=0.0
94 'Manifest',
95 'PruneCruft',
96 'ManifestSkip',
97 'RunExtraTests',
98 1 ▶ sub { $_[0]->pluginset_release_management }, # before test/confirm for before-release verification
Subroutine __ANON__: called CC=1 SCAR=0.0
99 'TestRelease',
100 'ConfirmRelease',
101 1 ▶ sub { $_[0]->pluginset_releaser },
Subroutine __ANON__: called CC=1 SCAR=0.0
102 ['MetaNoIndex' => { directory => [qw(t xt inc share eg examples)] }],
103 1 ▶ sub { $_[0]->pluginset_metaprovides },
Subroutine __ANON__: called CC=1 SCAR=0.0
104 'ShareDir',
105 1 ▶ sub { $_[0]->pluginset_execdir },
Subroutine __ANON__: called CC=1 SCAR=0.0
106 ],
107 5 => [
108 2 ▶ sub { $_[0]->pluginset_gatherer },
Subroutine __ANON__: called CC=1 SCAR=0.0
109 'MetaYAML',
110 'MetaJSON',
111 'License',
112 'Pod2Readme',
113 'PodSyntaxTests',
114 'Test::ReportPrereqs',
115 ['Test::Compile' => { xt_mode => 1 }],
116 2 ▶ sub { $_[0]->pluginset_installer },
Subroutine __ANON__: called CC=1 SCAR=0.0
117 'Manifest',
118 'PruneCruft',
119 ['PruneFiles' => { filename => ['README.pod'] }],
120 'ManifestSkip',
121 'RunExtraTests',
122 2 ▶ sub { $_[0]->pluginset_release_management }, # before test/confirm for before-release verification
Subroutine __ANON__: called CC=1 SCAR=0.0
123 'TestRelease',
124 'ConfirmRelease',
125 2 ▶ sub { $_[0]->pluginset_releaser },
Subroutine __ANON__: called CC=1 SCAR=0.0
126 ['MetaNoIndex' => { directory => [qw(t xt inc share eg examples)] }],
127 2 ▶ sub { $_[0]->pluginset_metaprovides },
Subroutine __ANON__: called CC=1 SCAR=0.0
128 'ShareDir',
129 2 ▶ sub { $_[0]->pluginset_execdir },
Subroutine __ANON__: called CC=1 SCAR=0.0
130 ],
131 6 => [
132 3 ▶ sub { $_[0]->pluginset_gatherer },
Subroutine __ANON__: called CC=1 SCAR=0.0
133 'MetaYAML',
134 'MetaJSON',
135 'License',
136 'Pod2Readme',
137 'PodSyntaxTests',
138 'Test::ReportPrereqs',
139 ['Test::Compile' => { xt_mode => 1 }],
140 'MetaMergeFile',
141 'PrereqsFile',
142 3 ▶ sub { $_[0]->pluginset_installer },
Subroutine __ANON__: called CC=1 SCAR=0.0
143 'Manifest',
144 'PruneCruft',
145 ['PruneFiles' => { filename => ['README.pod'] }],
146 'ManifestSkip',
147 'RunExtraTests',
148 3 ▶ sub { $_[0]->pluginset_release_management }, # before test/confirm for before-release verification
Subroutine __ANON__: called CC=1 SCAR=0.0
149 'TestRelease',
150 'ConfirmRelease',
151 3 ▶ sub { $_[0]->pluginset_releaser },
Subroutine __ANON__: called CC=1 SCAR=0.0
152 ['MetaNoIndex' => { directory => [qw(t xt inc share eg examples)] }],
153 3 ▶ sub { $_[0]->pluginset_metaprovides },
Subroutine __ANON__: called CC=1 SCAR=0.0
154 'ShareDir',
155 3 ▶ sub { $_[0]->pluginset_execdir },
Subroutine __ANON__: called CC=1 SCAR=0.0
156 11 ],
157 );
158  
159 11 my %allowed_installers = (
160 DistBuild => 1,
161 MakeMaker => 1,
162 'MakeMaker::Awesome' => 1,
163 ModuleBuild => 1,
164 ModuleBuildTiny => 1,
165 'ModuleBuildTiny::Fallback' => 1,
166 );
167  
168 11 my %option_requires = (
169 installer => 2,
170 managed_versions => 3,
171 regenerate => 3,
172 );
173  
174 has revision => (
175 is => 'ro',
176 lazy => 1,
177 12 ▶ default => sub { $_[0]->payload->{revision} // 1 },
Subroutine __ANON__: called CC=2 SCAR=7.6
Condition50%1/2
$_[0]->payload->{"revision"} // 1
l!l
120
MC/DC0%0/1
$_[0]->payload->{"revision"} // 1
$_[0]->payload->{"revision"}
Truth table50%1/2
A
A= $_[0]->payload->{"revision"}
Aresult
11
00
178 11 );
179  
180 has installer => (
181 is => 'ro',
182 lazy => 1,
183 11 ▶ default => sub { $_[0]->payload->{installer} // 'MakeMaker' },
Subroutine __ANON__: called CC=2 SCAR=6.9
Condition100%2/2
$_[0]->payload->{"installer"} // "MakeMaker"
l!l
65
MC/DC100%1/1
$_[0]->payload->{"installer"} // "MakeMaker"
$_[0]->payload->{"installer"}
Truth table100%2/2
A
A= $_[0]->payload->{"installer"}
Aresult
11
00
184 11 );
185  
186 has managed_versions => (
187 is => 'ro',
188 lazy => 1,
189 7 ▶ default => sub { $_[0]->payload->{managed_versions} // 0 },
Subroutine __ANON__: called CC=2 SCAR=6.9
Condition100%2/2
$_[0]->payload->{"managed_versions"} // 0
l!l
43
MC/DC100%1/1
$_[0]->payload->{"managed_versions"} // 0
$_[0]->payload->{"managed_versions"}
Truth table100%2/2
A
A= $_[0]->payload->{"managed_versions"}
Aresult
11
00
190 11 );
191  
192 has regenerate => (
193 is => 'ro',
194 lazy => 1,
195 7 ▶ default => sub { $_[0]->payload->{regenerate} // [] },
Subroutine __ANON__: called CC=2 SCAR=7.6
Condition50%1/2
$_[0]->payload->{"regenerate"} // []
l!l
07
MC/DC0%0/1
$_[0]->payload->{"regenerate"} // []
$_[0]->payload->{"regenerate"}
Truth table50%1/2
A
A= $_[0]->payload->{"regenerate"}
Aresult
11
00
196 11 );
197  
198 12 ▶sub mvp_multivalue_args { qw(regenerate) }
Subroutine mvp_multivalue_args: called CC=1 SCAR=0.0
199  
200 12 ▶sub configure {
Subroutine configure: called CC=7 SCAR=19.6
Pod undocumented
201 12 my $self = shift;
202 12 my $name = $self->name;
203 12 my $revision = $self->revision;
204 die "Unknown [$name] revision specified: $revision\n"
205 12 ▶ unless exists $revisions{$revision};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $revisions{$revision} 0 12 12
206 12 my @plugins = @{$revisions{$revision}};
207
208 12 foreach my $option (keys %option_requires) {
209 36 my $required = $option_requires{$option};
210 die "Option $option requires revision $required\n"
211 36 ▶ if exists $self->payload->{$option} and $required > $revision;
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->payload->{$option} and $required > $revision 0 36 36
Condition66%2/3
exists $self->payload->{$option} and $required > $revision
!ll&&!rl&&r
26100
MC/DC0%0/2
exists $self->payload->{$option} and $required > $revision
exists $self->payload->{$option} $required > $revision
Truth table66%2/3
A and B
A= exists $self->payload->{$option}B= $required > $revision
ABresult
0X0
100
111
212 }
213
214 12 foreach my $plugin (@plugins) {
215 264 ▶ if (ref $plugin eq 'CODE') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $plugin eq 'CODE') { } 55 209 264
216 55 $self->add_plugins($plugin->($self));
217 } else {
218 209 $self->add_plugins($plugin);
219 }
220 }
221 }
222  
223 7 ▶sub gather_plugin { 'GatherDir' }
Subroutine gather_plugin: called CC=1 SCAR=0.0
Pod undocumented
224  
225 7 ▶sub pluginset_gatherer {
Subroutine pluginset_gatherer: called CC=2 SCAR=7.0
Pod undocumented
226 7 my ($self) = @_;
227 7 my @copy = @{$self->regenerate};
228 7 ▶ return [$self->gather_plugin => { exclude_filename => [@copy] }] if @copy;
Branch: 1 branch
BranchTrueFalseTotal
if @copy 0 7 7
229 7 return $self->gather_plugin;
230 }
231  
232 11 ▶sub pluginset_installer {
Subroutine pluginset_installer: called CC=2 SCAR=7.0
Pod undocumented
233 11 my ($self) = @_;
234 11 my $installer = $self->installer;
235 die "Unsupported installer $installer\n"
236 11 ▶ unless $allowed_installers{$installer};
Branch: 1 branch
BranchTrueFalseTotal
unless $allowed_installers{$installer} 0 11 11
237 11 return "$installer";
238 }
239  
240 7 ▶sub pluginset_release_management {
Subroutine pluginset_release_management: called CC=4 SCAR=13.9
Pod undocumented
241 7 my ($self) = @_;
242 7 my $versions = $self->managed_versions;
243 7 my @copy_files = @{$self->regenerate};
244 7 my @plugins;
245 7 ▶ push @plugins, 'RewriteVersion',
Branch: 1 branch
BranchTrueFalseTotal
if $versions 4 3 7
246 [NextRelease => { format => '%-9v %{yyyy-MM-dd HH:mm:ss VVV}d%{ (TRIAL RELEASE)}T' }]
247 if $versions;
248 7 ▶ push @plugins,
Branch: 1 branch
BranchTrueFalseTotal
if @copy_files 0 7 7
249 [CopyFilesFromRelease => { filename => [@copy_files] }],
250 ['Regenerate::AfterReleasers' => { plugin => $self->name . '/CopyFilesFromRelease' }],
251 if @copy_files;
252 7 ▶ push @plugins, 'BumpVersionAfterRelease' if $versions;
Branch: 1 branch
BranchTrueFalseTotal
if $versions 4 3 7
253 7 return @plugins;
254 }
255  
256 12 ▶sub pluginset_releaser {
Subroutine pluginset_releaser: called CC=2 SCAR=7.2
Pod undocumented
257 12 my ($self) = @_;
258 12 ▶ return $ENV{FAKE_RELEASE} ? 'FakeRelease' : 'UploadToCPAN';
Branch: 1 branch
BranchTrueFalseTotal
$ENV{'FAKE_RELEASE'} ? : 0 12 12
259 }
260  
261 7 ▶sub pluginset_metaprovides {
Subroutine pluginset_metaprovides: called CC=2 SCAR=6.9
Pod undocumented
262 7 my ($self) = @_;
263 7 ▶ if ($self->managed_versions) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->managed_versions) { } 4 3 7
264 4 return 'MetaProvides::Package';
265 } else {
266 3 return ['MetaProvides::Package' => { inherit_version => 0 }];
267 }
268 }
269  
270 11 ▶sub pluginset_execdir {
Subroutine pluginset_execdir: called CC=2 SCAR=6.9
Pod undocumented
271 11 my ($self) = @_;
272 11 my $installer = $self->installer;
273 11 ▶ if ($installer =~ m/^ModuleBuildTiny/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($installer =~ /^ModuleBuildTiny/) { } 2 9 11
274 2 return ['ExecDir' => {dir => 'script'}];
275 } else {
276 9 return 'ExecDir';
277 }
278 }
279  
280 11 __PACKAGE__->meta->make_immutable;
281 11 1;
282  
283 =head1 NAME
284  
285 Dist::Zilla::PluginBundle::Starter - A minimal Dist::Zilla plugin bundle
286  
287 =head1 SYNOPSIS
288  
289 ; dist.ini
290 name = My-Cool-Distribution
291 author = Example Jones <jones@example.com>
292 license = Perl_5
293 copyright_holder = Example Jones
294 copyright_year = 2017
295 version = 0.001
296
297 [@Starter] ; all that is needed to start
298 revision = 6 ; always defaults to revision 1
299
300 ; configuring examples
301 installer = ModuleBuildTiny
302 -remove = GatherDir ; to use [Git::GatherDir] instead, for example
303 ExecDir.dir = script ; change the directory used by [ExecDir]
304 managed_versions = 1 ; uses the main module version, and bumps module versions after release
305 regenerate = LICENSE ; copy LICENSE to root after release and dzil regenerate
306  
307 [@Starter::Git] ; drop-in variant bundle for git workflows
308 revision = 6 ; requires/defaults to revision 3
309  
310 =head1 DESCRIPTION
311  
312 The C<[@Starter]> plugin bundle for L<Dist::Zilla> is designed to do the
313 minimal amount of work to release a complete distribution reliably. It is
314 similar in purpose to L<[@Basic]|Dist::Zilla::PluginBundle::Basic>, but with
315 additional features to stay up to date and allow greater customization. The
316 selection of included plugins is intended to be unopinionated and unobtrusive,
317 so that it is usable for any well-formed CPAN distribution.
318  
319 C<[@Starter]> supports bundle revisions specified as an option, in order to
320 allow authors to opt-in to future changes to distribution packaging and
321 releasing practices. Existing revisions and the default revision number will
322 not be changed, to preserve consistent functionality in existing F<dist.ini>
323 configurations.
324  
325 You probably want L<[@Starter::Git]|Dist::Zilla::PluginBundle::Starter::Git>,
326 an extension of this bundle, if you are using a git-based workflow.
327  
328 L<Dist::Milla> is another simple, if opinionated, way to use L<Dist::Zilla>
329 without requiring any configuration ("convention over configuration"), and
330 performing all of the tasks in L</"EXTENDING"> by default. The C<[@Starter]>
331 bundle can also be configured to operate much like L<Dist::Milla>, as in the
332 L</"Dist::Milla equivalent"> example.
333  
334 =head1 GETTING STARTED
335  
336 The L<Dist::Zilla::Starter> guide is a starting point if you are new to
337 L<Dist::Zilla> or CPAN distribution building.
338  
339 For one-line initialization of a new C<[@Starter]>-based distribution, try
340 L<Dist::Zilla::MintingProfile::Starter> (or
341 L<Dist::Zilla::MintingProfile::Starter::Git>).
342  
343 Migrating from C<[@Basic]> is easy for most cases. The core of the bundle is
344 the same, so just make sure to remove any extra plugins that C<[@Starter]>
345 already includes, and configure the included plugins if needed. Migrating a
346 more complex set of plugins, including some that interact with the additional
347 generated files, may require more careful consideration.
348  
349 See L</"EXAMPLES"> for example configurations of this bundle, L</"CONFIGURING">
350 for suggestions to customize the bundle to your needs, and L</"EXTENDING"> for
351 examples of other common tasks L<Dist::Zilla> can facilitate.
352  
353 =head1 OPTIONS
354  
355 C<[@Starter]> currently only has a few direct options; it can be further
356 configured by the composed roles, as in L</"CONFIGURING">.
357  
358 =head2 revision
359  
360 [@Starter]
361 revision = 6
362  
363 Selects the revision to use, from L</"REVISIONS">. Defaults to revision 1.
364  
365 =head2 installer
366  
367 Requires revision 2 or higher.
368  
369 [@Starter]
370 revision = 2
371 installer = ModuleBuildTiny
372  
373 [@Starter]
374 revision = 2
375 installer = MakeMaker::Awesome
376 MakeMaker::Awesome.WriteMakefile_arg[0] = (clean => { FILES => 't/generated/*' })
377  
378 [@Starter]
379 revision = 5
380 installer = ModuleBuild
381 ModuleBuild.mb_class = My::Module::Builder
382  
383 [@Starter]
384 revision = 6
385 installer = DistBuild
386 DistBuild.auto_plugin_requires = 1
387  
388 The default installer is L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker>, which
389 works with no extra configuration for most cases. The C<installer> option can
390 be used to replace it with one of the following supported installers, which can
391 then be configured in the same way as shown in L</"CONFIGURING">.
392  
393 L<[MakeMaker::Awesome]|Dist::Zilla::Plugin::MakeMaker::Awesome> is useful if
394 you need to customize the generated F<Makefile.PL>.
395  
396 L<[ModuleBuildTiny]|Dist::Zilla::Plugin::ModuleBuildTiny> will generate a
397 simple F<Build.PL> using L<Module::Build::Tiny>, but this may not work
398 correctly with old versions of the L<CPAN>.pm installer or if you use features
399 incompatible with L<Module::Build::Tiny>.
400  
401 L<[ModuleBuildTiny::Fallback]|Dist::Zilla::Plugin::ModuleBuildTiny::Fallback>
402 generates a more complex F<Build.PL> that uses L<Module::Build::Tiny> by
403 default, but falls back to L<Module::Build> on old versions of the L<CPAN>.pm
404 installer that don't understand configure dependencies.
405  
406 When using a L<Module::Build::Tiny>-based installer, the
407 L<[ExecDir]|Dist::Zilla::Plugin::ExecDir> plugin will be set to mark the
408 F<script/> directory for executables instead of the default F<bin/>.
409  
410 Since revision 5, L<[ModuleBuild]|Dist::Zilla::Plugin::ModuleBuild> is
411 supported as an installer, and will generate a F<Build.PL> that uses
412 L<Module::Build>. This is not generally recommended unless converting a
413 distribution that is already using a L<Module::Build> subclass.
414  
415 Since revision 6, L<[DistBuild]|Dist::Zilla::Plugin::DistBuild> is supported
416 as an installer, and will generate a F<Build.PL> that uses L<Dist::Build>.
417  
418 =head2 managed_versions
419  
420 Requires revision 3 or higher.
421  
422 [@Starter]
423 revision = 3
424 managed_versions = 1
425  
426 With C<managed_versions> set, C<[@Starter]> will use an additional set of
427 plugins to manage your module versions when releasing, while leaving them in
428 place in the source files.
429  
430 L<[RewriteVersion]|Dist::Zilla::Plugin::RewriteVersion> will read the
431 distribution version from the main module, and set all other module versions to
432 match in the build. L<[NextRelease]|Dist::Zilla::Plugin::NextRelease> replaces
433 C<{{$NEXT}}> in your F<Changes> file with a line containing the distribution
434 version and build date/time. Finally,
435 L<[BumpVersionAfterRelease]|Dist::Zilla::Plugin::BumpVersionAfterRelease> will
436 bump the versions in your source module files after a release.
437  
438 When using this option, you B<must> have the distribution version set in your
439 main module in a form like C<our $VERSION = '1.234';>, rather than in
440 F<dist.ini>. Other modules and scripts must also have similar version
441 declarations to be updated appropriately. You can set your distribution's
442 version manually by changing the version of your main module, or by setting the
443 C<V> environment variable when building or releasing. See the documentation for
444 each plugin mentioned above for details on configuring them, which can be done
445 in the usual config-slicing way as shown in L</"CONFIGURING">.
446  
447 This option also enables the C<inherit_version> option for
448 L<[MetaProvides::Package]|Dist::Zilla::Plugin::MetaProvides::Package> since all
449 module versions are matched to the main module in this configuration.
450  
451 =head2 regenerate
452  
453 Requires revision 3 or higher.
454  
455 [@Starter]
456 revision = 3
457 regenerate = INSTALL
458 regenerate = README
459  
460 The specified generated files will be copied to the root directory upon
461 release using L<[CopyFilesFromRelease]|Dist::Zilla::Plugin::CopyFilesFromRelease>,
462 and excluded from the C<[GatherDir]> plugin in use. Note: if you remove the
463 built-in C<[GatherDir]> plugin to use one separately, you must exclude copied
464 files from that plugin yourself. Additionally,
465 L<[Regenerate::AfterReleasers]|Dist::Zilla::Plugin::Regenerate::AfterReleasers>
466 is applied to C<[CopyFilesFromRelease]> to allow these files to be generated
467 and copied on demand outside of a release using
468 L<< C<dzil regenerate>|Dist::Zilla::App::Command::regenerate >>.
469  
470 =head1 REVISIONS
471  
472 The C<[@Starter]> plugin bundle supports the following revisions.
473  
474 =head2 Revision 6
475  
476 Revision 6 is the current set of best practices, equivalent to using the
477 following plugins if not configured further:
478  
479 =over 2
480  
481 =item L<[GatherDir]|Dist::Zilla::Plugin::GatherDir>
482  
483 =item L<[MetaYAML]|Dist::Zilla::Plugin::MetaYAML>
484  
485 =item L<[MetaJSON]|Dist::Zilla::Plugin::MetaJSON>
486  
487 =item L<[License]|Dist::Zilla::Plugin::License>
488  
489 =item L<[Pod2Readme]|Dist::Zilla::Plugin::Pod2Readme>
490  
491 =item L<[PodSyntaxTests]|Dist::Zilla::Plugin::PodSyntaxTests>
492  
493 =item L<[Test::ReportPrereqs]|Dist::Zilla::Plugin::Test::ReportPrereqs>
494  
495 =item L<[Test::Compile]|Dist::Zilla::Plugin::Test::Compile>
496  
497 xt_mode = 1
498  
499 =item L<[MetaMergeFile]|Dist::Zilla::Plugin::MetaMergeFile>
500  
501 =item L<[PrereqsFile]|Dist::Zilla::Plugin::PrereqsFile>
502  
503 =item L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker>
504  
505 =item L<[Manifest]|Dist::Zilla::Plugin::Manifest>
506  
507 =item L<[PruneCruft]|Dist::Zilla::Plugin::PruneCruft>
508  
509 =item L<[PruneFiles]|Dist::Zilla::Plugin::PruneFiles>
510  
511 filename = README.pod
512  
513 =item L<[ManifestSkip]|Dist::Zilla::Plugin::ManifestSkip>
514  
515 =item L<[RunExtraTests]|Dist::Zilla::Plugin::RunExtraTests>
516  
517 =item L<[TestRelease]|Dist::Zilla::Plugin::TestRelease>
518  
519 =item L<[ConfirmRelease]|Dist::Zilla::Plugin::ConfirmRelease>
520  
521 =item L<[UploadToCPAN]|Dist::Zilla::Plugin::UploadToCPAN>
522  
523 =item L<[MetaNoIndex]|Dist::Zilla::Plugin::MetaNoIndex>
524  
525 directory = t
526 directory = xt
527 directory = inc
528 directory = share
529 directory = eg
530 directory = examples
531  
532 =item L<[MetaProvides::Package]|Dist::Zilla::Plugin::MetaProvides::Package>
533  
534 inherit_version = 0
535  
536 =item L<[ShareDir]|Dist::Zilla::Plugin::ShareDir>
537  
538 =item L<[ExecDir]|Dist::Zilla::Plugin::ExecDir>
539  
540 =back
541  
542 Revision 6 differs from Revision 5 as follows:
543  
544 =over 2
545  
546 =item *
547  
548 Includes an instance of the L<[MetaMergeFile]|Dist::Zilla::Plugin::MetaMergeFile>
549 and L<[PrereqsFile]|Dist::Zilla::Plugin::PrereqsFile> plugins to allow specifying
550 arbitrary CPAN metadata in F<metamerge.yml>/F<metamerge.json> and distribution
551 prerequisites in F<prereqs.yml>/F<prereqs.json>. These plugins have no effect if
552 the corresponding files are not present in the source tree.
553  
554 =item *
555  
556 The L</"installer"> option now supports C<DistBuild>.
557  
558 =back
559  
560 =head2 Revision 5
561  
562 Revision 5 differs from Revision 4 as follows:
563  
564 =over 2
565  
566 =item *
567  
568 Includes an instance of the L<[PruneFiles]|Dist::Zilla::Plugin::PruneFiles>
569 plugin to remove F<README.pod> from the distribution build if present. The CPAN
570 toolchain expects C<.pod> files to be documentation and installs them alongside
571 the module files, sometimes even if they are outside the F<lib/> subdirectory,
572 due to historical distribution layouts. But this is not the purpose of
573 F<README.pod>, so it is excluded from the build to avoid cluttering users'
574 install locations and confusing MetaCPAN and similar documentation indexes.
575 F<README.pod> files generated in the source tree using
576 L<[ReadmeAnyFromPod]|Dist::Zilla::Plugin::ReadmeAnyFromPod> (with
577 C<location = root>) are already automatically excluded from the build by that
578 plugin.
579  
580 =item *
581  
582 The L</"installer"> option now supports C<ModuleBuild>.
583  
584 =back
585  
586 =head2 Revision 4
587  
588 Revision 4 differs from Revision 3 by removing the
589 L<[MetaConfig]|Dist::Zilla::Plugin::MetaConfig> plugin, because it adds
590 significant clutter to the generated META files without much benefit. It can
591 easily be added to the F<dist.ini> if desired.
592  
593 =head2 Revision 3
594  
595 Revision 3 differs from Revision 2 in that it additionally supports the
596 L</"managed_versions"> and L</"regenerate"> options, and variant bundles like
597 L<[@Starter::Git]|Dist::Zilla::PluginBundle::Starter::Git>.
598  
599 =head2 Revision 2
600  
601 Revision 2 differs from Revision 1 as follows:
602  
603 =over 2
604  
605 =item *
606  
607 Sets the option
608 L<"inherit_version" in [MetaProvides::Package]|Dist::Zilla::Plugin::MetaProvides::Package/"inherit_version">
609 to 0 by default, so that C<provides> metadata will use individual module
610 versions if they differ from the distribution version.
611  
612 =item *
613  
614 L<[Pod2Readme]|Dist::Zilla::Plugin::Pod2Readme> is used instead of
615 L<[ReadmeAnyFromPod]|Dist::Zilla::Plugin::ReadmeAnyFromPod> to generate the
616 plaintext F<README>, as it is a simpler plugin for this purpose. It takes the
617 same C<filename> and C<source_filename> options, but does not allow further
618 configuration, and does not automatically use a C<.pod> file as the source.
619  
620 =item *
621  
622 The L</"installer"> option is now supported to change the installer plugin.
623  
624 =back
625  
626 =head2 Revision 1
627  
628 Revision 1 is the default if no revision is specified, and differs from
629 L<[@Basic]|Dist::Zilla::PluginBundle::Basic> as follows:
630  
631 =over 2
632  
633 =item *
634  
635 Uses L<[ReadmeAnyFromPod]|Dist::Zilla::Plugin::ReadmeAnyFromPod>
636 instead of L<[Readme]|Dist::Zilla::Plugin::Readme>.
637  
638 =item *
639  
640 Uses L<[RunExtraTests]|Dist::Zilla::Plugin::RunExtraTests> instead of
641 L<[ExtraTests]|Dist::Zilla::Plugin::ExtraTests>.
642  
643 =item *
644  
645 Includes the following additional plugins:
646 L<[MetaJSON]|Dist::Zilla::Plugin::MetaJSON>,
647 L<[PodSyntaxTests]|Dist::Zilla::Plugin::PodSyntaxTests>,
648 L<[Test::ReportPrereqs]|Dist::Zilla::Plugin::Test::ReportPrereqs>,
649 L<[Test::Compile]|Dist::Zilla::Plugin::Test::Compile>,
650 L<[MetaConfig]|Dist::Zilla::Plugin::MetaConfig>,
651 L<[MetaNoIndex]|Dist::Zilla::Plugin::MetaNoIndex>,
652 L<[MetaProvides::Package]|Dist::Zilla::Plugin::MetaProvides::Package>.
653  
654 =back
655  
656 =head1 EXAMPLES
657  
658 Some example F<dist.ini> configurations to get started with.
659  
660 =head2 Just the basics
661  
662 name = Acme-Foo
663 author = Jane Doe <example@example.com>
664 license = Artistic_2_0
665 copyright_holder = Jane Doe
666 copyright_year = 2019
667 version = 1.00
668  
669 [@Starter]
670 revision = 6
671  
672 [Prereqs / RuntimeRequires]
673 perl = 5.010001
674 Exporter = 5.57
675 Path::Tiny = 0
676  
677 [Prereqs / TestRequires]
678 Test::More = 0.88
679  
680 =head2 Managed boilerplate
681  
682 name = Acme-Foo
683 author = Jane Doe <example@example.com>
684 license = Artistic_2_0
685 copyright_holder = Jane Doe
686 copyright_year = 2019
687  
688 [@Starter::Git]
689 revision = 6
690 managed_versions = 1
691 regenerate = Makefile.PL
692 regenerate = META.json
693 regenerate = LICENSE
694  
695 [AutoPrereqs]
696  
697 =head2 Dist::Milla equivalent
698  
699 [CheckChangesHasContent]
700  
701 [ReadmeAnyFromPod]
702 type = markdown
703 filename = README.md
704 location = root
705 phase = release
706 [Regenerate::AfterReleasers]
707 plugin = ReadmeAnyFromPod
708  
709 [@Starter::Git]
710 revision = 6
711 installer = ModuleBuildTiny
712 managed_versions = 1
713 regenerate = Build.PL
714 regenerate = META.json
715 regenerate = LICENSE
716 ExecDir.dir = script
717 Release_Commit.allow_dirty[] = README.md
718 BumpVersionAfterRelease.munge_build_pl = 0
719  
720 [NameFromDirectory]
721 [LicenseFromModule]
722 override_author = 1
723 [Prereqs::FromCPANfile]
724 [StaticInstall]
725 mode = auto
726 [GithubMeta]
727 issues = 1
728 [Git::Contributors]
729  
730 =head1 CONFIGURING
731  
732 By using the L<PluginRemover|Dist::Zilla::Role::PluginBundle::PluginRemover> or
733 L<Config::Slicer|Dist::Zilla::Role::PluginBundle::Config::Slicer> role options,
734 the C<[@Starter]> bundle's included plugins can be customized as desired. Here
735 are some examples:
736  
737 =head2 GatherDir
738  
739 If the distribution is using git source control, it is often helpful to replace
740 the default L<[GatherDir]|Dist::Zilla::Plugin::GatherDir> plugin with
741 L<[Git::GatherDir]|Dist::Zilla::Plugin::Git::GatherDir>. (Note: The
742 L<[@Starter::Git]|Dist::Zilla::PluginBundle::Starter::Git> variant of this
743 bundle uses C<[Git::GatherDir]> by default.)
744  
745 [Git::GatherDir]
746 [@Starter]
747 -remove = GatherDir
748  
749 The included L<[GatherDir]|Dist::Zilla::Plugin::GatherDir> plugin can
750 alternatively be configured directly. (See
751 L<Config::MVP::Slicer/"CONFIGURATION SYNTAX"> for an explanation of the
752 subscripts for slicing array attributes.)
753  
754 [@Starter]
755 GatherDir.include_dotfiles = 1
756 GatherDir.exclude_filename[0] = foo_bar.txt
757 GatherDir.prune_directory[] = ^temp
758  
759 =head2 Readme
760  
761 The L<[Pod2Readme]|Dist::Zilla::Plugin::Pod2Readme> or
762 L<[ReadmeAnyFromPod]|Dist::Zilla::Plugin::ReadmeAnyFromPod> plugin (depending
763 on bundle revision) generates a plaintext F<README> from the POD text in the
764 distribution's L<Dist::Zilla/"main_module"> by default, but can be configured
765 to look elsewhere. The standard F<README> should always be plaintext, but in
766 order to generate a non-plaintext F<README> in addition,
767 L<[ReadmeAnyFromPod]|Dist::Zilla::Plugin::ReadmeAnyFromPod> can simply be used
768 separately.
769  
770 [@Starter]
771 revision = 2
772 Pod2Readme.source_filename = bin/foobar
773
774 [ReadmeAnyFromPod / Markdown_Readme]
775 type = markdown
776 filename = README.md
777
778 [ReadmeAnyFromPod / Pod_Readme]
779 type = pod
780 location = root ; do not include pod readmes in the build!
781 phase = release ; avoid changing files in the root with dzil build or dzil test
782 [Regenerate::AfterReleasers] ; allows regenerating with dzil regenerate
783 plugin = Pod_Readme
784  
785 Alternatively, you can remove the default F<README> plugin to ship a manually
786 maintained file, or generate one with another plugin such as
787 L<[Readme::Brief]|Dist::Zilla::Plugin::Readme::Brief>.
788  
789 [Readme::Brief]
790 [@Starter]
791 revision = 2
792 -remove = Pod2Readme
793  
794 =head2 MetaNoIndex
795  
796 The distribution may include additional files or directories that should not
797 have their contents indexed as CPAN modules. (See
798 L<Config::MVP::Slicer/"CONFIGURATION SYNTAX"> for an explanation of the
799 subscripts for slicing array attributes.)
800  
801 [@Starter]
802 MetaNoIndex.file[0] = eggs/FooBar.pm
803 MetaNoIndex.directory[a] = eggs
804 MetaNoIndex.directory[b] = bacon
805  
806 =head2 MetaProvides
807  
808 The L<[MetaProvides::Package]|Dist::Zilla::Plugin::MetaProvides::Package>
809 plugin will use the distribution's version (as set in F<dist.ini> or by a
810 plugin) as the version of each module when populating the C<provides> metadata
811 by default. If the distribution does not have uniform module versions, the
812 plugin can be configured to reflect each module's hardcoded version where
813 available, by setting the C<inherit_version> option to 0 (the default in bundle
814 L</"Revision 2">).
815  
816 [@Starter]
817 MetaProvides::Package.inherit_version = 0 ; default in revision 2
818  
819 With this option set to 0, it will use the main distribution version as a
820 fallback for any module where a version is not found. This can also be
821 overridden, so that if no version is found for a module, no version will be
822 specified for it in metadata, by setting C<inherit_missing> to 0 as well.
823  
824 [@Starter]
825 MetaProvides::Package.inherit_version = 0
826 MetaProvides::Package.inherit_missing = 0
827  
828 =head2 ExecDir
829  
830 Some distributions use the F<script/> directory instead of F<bin/> (the
831 L<[ExecDir]|Dist::Zilla::Plugin::ExecDir> default) for executable scripts.
832  
833 [@Starter]
834 ExecDir.dir = script
835  
836 =head2 Versions
837  
838 When using the L</"managed_versions"> option, the additional plugins can be
839 directly configured in various ways to suit your versioning needs.
840  
841 [@Starter]
842 revision = 3
843 managed_versions = 1
844
845 ; configuration examples
846 RewriteVersion.global = 1
847 BumpVersionAfterRelease.munge_makefile_pl = 0
848 NextRelease.filename = ChangeLog
849 NextRelease.format = %-5v %{yyyy-MM-dd}d
850  
851 =head1 EXTENDING
852  
853 This bundle includes a basic set of plugins for releasing a distribution, but
854 there are many more common non-intrusive tasks that L<Dist::Zilla> can help
855 with simply by using additional plugins in the F<dist.ini>. You can install all
856 plugins required by a F<dist.ini> by running
857 C<dzil authordeps --missing | cpanm> or with
858 L<< C<dzil installdeps>|Dist::Zilla::App::Command::installdeps >>.
859  
860 =head2 Name
861  
862 To automatically set the distribution name from the project directory name, use
863 L<[NameFromDirectory]|Dist::Zilla::Plugin::NameFromDirectory>.
864  
865 =head2 License and Copyright
866  
867 To extract the license and copyright information from the main module
868 documentation, and optionally set the author as well, use
869 L<[LicenseFromModule]|Dist::Zilla::Plugin::LicenseFromModule>.
870  
871 =head2 Changelog
872  
873 To automatically add the new release version to the distribution changelog,
874 use L<[NextRelease]|Dist::Zilla::Plugin::NextRelease> as the L</"managed_versions">
875 option does. To ensure the release has changelog entries, use
876 L<[CheckChangesHasContent]|Dist::Zilla::Plugin::CheckChangesHasContent>.
877  
878 =head2 Git
879  
880 To better integrate with a git workflow, use the plugins from
881 L<[@Git]|Dist::Zilla::PluginBundle::Git>, as the
882 L<[@Starter::Git]|Dist::Zilla::PluginBundle::Starter::Git> variant of this
883 bundle does. To automatically add contributors to metadata from git commits,
884 use L<[Git::Contributors]|Dist::Zilla::Plugin::Git::Contributors>.
885  
886 =head2 Resources
887  
888 To automatically set resource metadata from an associated GitHub repository,
889 use L<[GithubMeta]|Dist::Zilla::Plugin::GithubMeta>. To set resource metadata
890 manually, use L<[MetaResources]|Dist::Zilla::Plugin::MetaResources>.
891  
892 Since L</"Revision 6"> or by including L<[MetaMergeFile]|Dist::Zilla::Plugin::MetaMergeFile>
893 with an earlier revision, resource metadata and other arbitrary metadata can be
894 specified in a F<metamerge.json> or F<metamerge.yml>.
895  
896 =head2 Prereqs
897  
898 To specify distribution prereqs in a L<cpanfile>, use
899 L<[Prereqs::FromCPANfile]|Dist::Zilla::Plugin::Prereqs::FromCPANfile>. To
900 specify prereqs in a F<prereqs.json> or F<prereqs.yml>, use
901 L<[PrereqsFile]|Dist::Zilla::Plugin::PrereqsFile>. To specify prereqs in
902 F<dist.ini>, use L<[Prereqs]|Dist::Zilla::Plugin::Prereqs>. To automatically
903 guess the distribution's prereqs by parsing the code, use
904 L<[AutoPrereqs]|Dist::Zilla::Plugin::AutoPrereqs>.
905  
906 Since L</"Revision 6">, L<[PrereqsFile]|Dist::Zilla::Plugin::PrereqsFile> is
907 enabled by default, but prereqs can still be specified with any other method.
908  
909 =head1 ENVIRONMENT
910  
911 The C<FAKE_RELEASE> environment variable is supported as in L<Dist::Milla> and
912 L<Minilla>. It replaces the L<[UploadToCPAN]|Dist::Zilla::Plugin::UploadToCPAN>
913 plugin with L<[FakeRelease]|Dist::Zilla::Plugin::FakeRelease>, to test the
914 release process (including any version bumping and commits!) without actually
915 uploading to CPAN.
916  
917 $ FAKE_RELEASE=1 dzil release
918  
919 =head1 BUGS
920  
921 Report any issues on the public bugtracker.
922  
923 =head1 AUTHOR
924  
925 Dan Book <dbook@cpan.org>
926  
927 =head1 COPYRIGHT AND LICENSE
928  
929 This software is Copyright (c) 2016 by Dan Book.
930  
931 This is free software, licensed under:
932  
933 The Artistic License 2.0 (GPL Compatible)
934  
935 =head1 SEE ALSO
936  
937 L<Dist::Zilla>, L<Dist::Zilla::PluginBundle::Basic>,
938 L<Dist::Zilla::Starter>, L<Dist::Zilla::PluginBundle::Starter::Git>,
939 L<Dist::Zilla::MintingProfile::Starter>, L<Dist::Milla>
↑ Summary Dist/Zilla/Starter.pm »