NAME
Dist::Zilla::PluginBundle::Starter - A minimal Dist::Zilla plugin bundle
SYNOPSIS
; dist.ini
name = My-Cool-Distribution
author = Example Jones <jones@example.com>
license = Perl_5
copyright_holder = Example Jones
copyright_year = 2016
version = 0.001
[@Starter] ; all that is needed to start
revision = 1 ; always defaults to revision 1
-remove = GatherDir ; to use [Git::GatherDir] instead, for example
ExecDir.dir = script ; change the directory used by [ExecDir]DESCRIPTION
The [@Starter] plugin bundle for Dist::Zilla is designed to do the minimal amount of work to release a complete distribution reliably. It is similar in purpose to [@Basic], but with additional features to stay up to date and allow greater customization. The selection of included plugins is intended to be unopinionated and unobtrusive, so that it is usable for any well-formed CPAN distribution.
[@Starter] composes the PluginRemover and Config::Slicer roles to make it easier to customize and extend. Also, it supports bundle revisions specified as an option, in order to incorporate future changes to distribution packaging and releasing practices. Existing revisions will not be changed to preserve backwards compatibility.
The FAKE_RELEASE environment variable is supported as in Dist::Milla and Minilla. It replaces the [UploadToCPAN] plugin with [FakeRelease], to test the release process (including any version bumping and commits!) without actually uploading to CPAN.
$ FAKE_RELEASE=1 dzil releaseREVISIONS
The [@Starter] plugin bundle currently includes only one revision.
1
Revision 1 is the default and is equivalent to using the following plugins:
- [GatherDir]
- [PruneCruft]
- [ManifestSkip]
- [MetaConfig]
- [MetaProvides::Package]
- [MetaNoIndex]
-
directory = t directory = xt directory = inc directory = share directory = eg directory = examples - [MetaYAML]
- [MetaJSON]
- [License]
- [ReadmeAnyFromPod]
- [ExecDir]
- [PodSyntaxTests]
- [Test::ReportPrereqs]
- [Test::Compile]
-
xt_mode = 1 - [MakeMaker]
- [Manifest]
- [TestRelease]
- [RunExtraTests]
- [ConfirmRelease]
- [UploadToCPAN]
This revision differs from [@Basic] as follows: using [ReadmeAnyFromPod] instead of [Readme]; using [RunExtraTests] instead of [ExtraTests]; and including the following additional plugins: [MetaJSON], [MetaConfig], [MetaProvides::Package], [MetaNoIndex], [PodSyntaxTests], [Test::ReportPrereqs], [Test::Compile].
CONFIGURING
By using the PluginRemover or Config::Slicer role options, you can customize the [@Starter] bundle's included plugins as desired. Here are some examples:
GatherDir
If you are using git source control, you may wish to replace the default [GatherDir] plugin with [Git::GatherDir].
[Git::GatherDir]
[@Starter]
-remove = GatherDirReadme
The [ReadmeAnyFromPod] plugin generates a plaintext README from the POD text in the distribution's "main_module" in Dist::Zilla by default, but can be configured to look elsewhere. The standard README should always be plaintext, but if you want to generate a non-plaintext README in addition, you can simply use the plugin a second time. Note that POD-format READMEs should not be included in the distribution build because they will get indexed and installed due to an oddity in CPAN installation tools.
[@Starter]
ReadmeAnyFromPod.source_filename = bin/foobar
[ReadmeAnyFromPod / Markdown_Readme]
type = markdown
filename = README.md
[ReadmeAnyFromPod / Pod_Readme]
type = pod
location = root ; do not include pod readmes in the build!ExecDir
Some distributions use the script directory instead of bin (the [ExecDir] default) for executable scripts.
[@Starter]
ExecDir.dir = scriptMetaNoIndex
You may wish to specify that additional files or directories are not indexed as CPAN modules. (See "CONFIGURATION SYNTAX" in Config::MVP::Slicer for an explanation of the subscripts for slicing array attributes.)
[@Starter]
MetaNoIndex.file[0] = eggs/FooBar.pm
MetaNoIndex.directory[a] = eggs
MetaNoIndex.directory[b] = baconEXTENDING
This bundle includes a basic set of plugins for releasing a distribution, but there are many more common non-intrusive tasks that Dist::Zilla can help with simply by using additional plugins in your dist.ini.
Name
To automatically set the distribution name from the current directory, use [NameFromDirectory].
License and Copyright
To extract the license and copyright information from the main module, and optionally set the author as well, use [LicenseFromModule].
Versions
To automatically extract the distribution's version from the main module and bump it after a release, you can use either [RewriteVersion] with [BumpVersionAfterRelease], or [VersionFromModule] with [ReversionOnRelease]. Don't mix these two approaches!
Changelog
To automatically add the new release version to the distribution changelog, use [NextRelease]. To ensure the release has changelog entries, use [CheckChangesHasContent].
Git
To better integrate with a git workflow, use the plugins from [@Git]. To automatically add contributors to metadata from git commits, use [Git::Contributors].
Resources
To automatically set resource metadata from an associated GitHub repository, use [GithubMeta]. To set resource metadata manually, use [MetaResources].
Prereqs
To automatically set distribution prereqs from a cpanfile, use [Prereqs::FromCPANfile]. To specify prereqs manually, use [Prereqs].
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2016 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)