Dist::Zilla::PluginBundle::Starter(3)

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   = 2017
  version = 0.001

  [@Starter]           ; all that is needed to start
  revision = 6         ; always defaults to revision 1

  ; configuring examples
  installer = ModuleBuildTiny
  -remove = GatherDir  ; to use [Git::GatherDir] instead, for example
  ExecDir.dir = script ; change the directory used by [ExecDir]
  managed_versions = 1 ; uses the main module version, and bumps module versions after release
  regenerate = LICENSE ; copy LICENSE to root after release and dzil regenerate

  [@Starter::Git]      ; drop-in variant bundle for git workflows
  revision = 6         ; requires/defaults to revision 3

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]" supports bundle revisions specified as an option, in order to allow authors to opt-in to future changes to distribution packaging and releasing practices. Existing revisions and the default revision number will not be changed, to preserve consistent functionality in existing dist.ini configurations.

You probably want [@Starter::Git], an extension of this bundle, if you are using a git-based workflow.

Dist::Milla is another simple, if opinionated, way to use Dist::Zilla without requiring any configuration ("convention over configuration"), and performing all of the tasks in "EXTENDING" by default. The "[@Starter]" bundle can also be configured to operate much like Dist::Milla, as in the "Dist::Milla equivalent" example.

GETTING STARTED
The Dist::Zilla::Starter guide is a starting point if you are new to Dist::Zilla or CPAN distribution building.

For one-line initialization of a new "[@Starter]"-based distribution, try Dist::Zilla::MintingProfile::Starter (or Dist::Zilla::MintingProfile::Starter::Git).

Migrating from "[@Basic]" is easy for most cases. The core of the bundle is the same, so just make sure to remove any extra plugins that "[@Starter]" already includes, and configure the included plugins if needed. Migrating a more complex set of plugins, including some that interact with the additional generated files, may require more careful consideration.

See "EXAMPLES" for example configurations of this bundle, "CONFIGURING" for suggestions to customize the bundle to your needs, and "EXTENDING" for examples of other common tasks Dist::Zilla can facilitate.

OPTIONS
"[@Starter]" currently only has a few direct options; it can be further configured by the composed roles, as in "CONFIGURING".

  revision
  [@Starter]
  revision = 6

Selects the revision to use, from "REVISIONS". Defaults to revision 1.

  installer
Requires revision 2 or higher.

  [@Starter]
  revision = 2
  installer = ModuleBuildTiny

  [@Starter]
  revision = 2
  installer = MakeMaker::Awesome
  MakeMaker::Awesome.WriteMakefile_arg[0] = (clean => { FILES => 't/generated/*' })

  [@Starter]
  revision = 5
  installer = ModuleBuild
  ModuleBuild.mb_class = My::Module::Builder

  [@Starter]
  revision = 6
  installer = DistBuild
  DistBuild.auto_plugin_requires = 1

The default installer is [MakeMaker], which works with no extra configuration for most cases. The "installer" option can be used to replace it with one of the following supported installers, which can then be configured in the same way as shown in "CONFIGURING".

[MakeMaker::Awesome] is useful if you need to customize the generated Makefile.PL.

[ModuleBuildTiny] will generate a simple Build.PL using Module::Build::Tiny, but this may not work correctly with old versions of the CPAN.pm installer or if you use features incompatible with Module::Build::Tiny.

[ModuleBuildTiny::Fallback] generates a more complex Build.PL that uses Module::Build::Tiny by default, but falls back to Module::Build on old versions of the CPAN.pm installer that don't understand configure dependencies.

When using a Module::Build::Tiny-based installer, the [ExecDir] plugin will be set to mark the script/ directory for executables instead of the default bin/.

Since revision 5, [ModuleBuild] is supported as an installer, and will generate a Build.PL that uses Module::Build. This is not generally recommended unless converting a distribution that is already using a Module::Build subclass.

Since revision 6, [DistBuild] is supported as an installer, and will generate a Build.PL that uses Dist::Build.

  managed_versions
Requires revision 3 or higher.

  [@Starter]
  revision = 3
  managed_versions = 1

With "managed_versions" set, "[@Starter]" will use an additional set of plugins to manage your module versions when releasing, while leaving them in place in the source files.

[RewriteVersion] will read the distribution version from the main module, and set all other module versions to match in the build. [NextRelease] replaces "{{$NEXT}}" in your Changes file with a line containing the distribution version and build date/time. Finally, [BumpVersionAfterRelease] will bump the versions in your source module files after a release.

When using this option, you must have the distribution version set in your main module in a form like "our $VERSION = '1.234';", rather than in dist.ini. Other modules and scripts must also have similar version declarations to be updated appropriately. You can set your distribution's version manually by changing the version of your main module, or by setting the "V" environment variable when building or releasing. See the documentation for each plugin mentioned above for details on configuring them, which can be done in the usual config-slicing way as shown in "CONFIGURING".

This option also enables the "inherit_version" option for [MetaProvides::Package] since all module versions are matched to the main module in this configuration.

  regenerate
Requires revision 3 or higher.

  [@Starter]
  revision = 3
  regenerate = INSTALL
  regenerate = README

The specified generated files will be copied to the root directory upon release using [CopyFilesFromRelease], and excluded from the "[GatherDir]" plugin in use. Note: if you remove the built-in "[GatherDir]" plugin to use one separately, you must exclude copied files from that plugin yourself. Additionally, [Regenerate::AfterReleasers] is applied to "[CopyFilesFromRelease]" to allow these files to be generated and copied on demand outside of a release using "dzil regenerate".

REVISIONS
The "[@Starter]" plugin bundle supports the following revisions.

  Revision 6
Revision 6 is the current set of best practices, equivalent to using the following plugins if not configured further:

[GatherDir]
[MetaYAML]
[MetaJSON]
[License]
[Pod2Readme]
[PodSyntaxTests]
[Test::ReportPrereqs]
[Test::Compile]
      xt_mode = 1

[MetaMergeFile]
[PrereqsFile]
[MakeMaker]
[Manifest]
[PruneCruft]
[PruneFiles]
      filename = README.pod

[ManifestSkip]
[RunExtraTests]
[TestRelease]
[ConfirmRelease]
[UploadToCPAN]
[MetaNoIndex]
      directory = t
      directory = xt
      directory = inc
      directory = share
      directory = eg
      directory = examples

[MetaProvides::Package]
      inherit_version = 0

[ShareDir]
[ExecDir]

Revision 6 differs from Revision 5 as follows:

•   Includes an instance of the [MetaMergeFile] and [PrereqsFile] plugins to allow specifying arbitrary CPAN metadata in metamerge.yml/metamerge.json and distribution prerequisites in prereqs.yml/prereqs.json. These plugins have no effect if the corresponding files are not present in the source tree.

•   The "installer" option now supports "DistBuild".

  Revision 5
Revision 5 differs from Revision 4 as follows:

•   Includes an instance of the [PruneFiles] plugin to remove README.pod from the distribution build if present. The CPAN toolchain expects ".pod" files to be documentation and installs them alongside the module files, sometimes even if they are outside the lib/ subdirectory, due to historical distribution layouts. But this is not the purpose of README.pod, so it is excluded from the build to avoid cluttering users' install locations and confusing MetaCPAN and similar documentation indexes. README.pod files generated in the source tree using [ReadmeAnyFromPod] (with "location = root") are already automatically excluded from the build by that plugin.

•   The "installer" option now supports "ModuleBuild".

  Revision 4
Revision 4 differs from Revision 3 by removing the [MetaConfig] plugin, because it adds significant clutter to the generated META files without much benefit. It can easily be added to the dist.ini if desired.

  Revision 3
Revision 3 differs from Revision 2 in that it additionally supports the "managed_versions" and "regenerate" options, and variant bundles like [@Starter::Git].

  Revision 2
Revision 2 differs from Revision 1 as follows:

•   Sets the option "inherit_version" in [MetaProvides::Package] to 0 by default, so that "provides" metadata will use individual module versions if they differ from the distribution version.

•   [Pod2Readme] is used instead of [ReadmeAnyFromPod] to generate the plaintext README, as it is a simpler plugin for this purpose. It takes the same "filename" and "source_filename" options, but does not allow further configuration, and does not automatically use a ".pod" file as the source.

•   The "installer" option is now supported to change the installer plugin.

  Revision 1
Revision 1 is the default if no revision is specified, and differs from [@Basic] as follows:

•   Uses [ReadmeAnyFromPod] instead of [Readme].

•   Uses [RunExtraTests] instead of [ExtraTests].

•   Includes the following additional plugins: [MetaJSON], [PodSyntaxTests], [Test::ReportPrereqs], [Test::Compile], [MetaConfig], [MetaNoIndex], [MetaProvides::Package].

EXAMPLES
Some example dist.ini configurations to get started with.

  Just the basics
  name    = Acme-Foo
  author  = Jane Doe <example@example.com>
  license = Artistic_2_0
  copyright_holder = Jane Doe
  copyright_year   = 2019
  version = 1.00

  [@Starter]
  revision = 6

  [Prereqs / RuntimeRequires]
  perl = 5.010001
  Exporter = 5.57
  Path::Tiny = 0

  [Prereqs / TestRequires]
  Test::More = 0.88

  Managed boilerplate
  name    = Acme-Foo
  author  = Jane Doe <example@example.com>
  license = Artistic_2_0
  copyright_holder = Jane Doe
  copyright_year   = 2019

  [@Starter::Git]
  revision = 6
  managed_versions = 1
  regenerate = Makefile.PL
  regenerate = META.json
  regenerate = LICENSE

  [AutoPrereqs]

  Dist::Milla equivalent
  [CheckChangesHasContent]

  [ReadmeAnyFromPod]
  type = markdown
  filename = README.md
  location = root
  phase = release
  [Regenerate::AfterReleasers]
  plugin = ReadmeAnyFromPod

  [@Starter::Git]
  revision = 6
  installer = ModuleBuildTiny
  managed_versions = 1
  regenerate = Build.PL
  regenerate = META.json
  regenerate = LICENSE
  ExecDir.dir = script
  Release_Commit.allow_dirty[] = README.md
  BumpVersionAfterRelease.munge_build_pl = 0

  [NameFromDirectory]
  [LicenseFromModule]
  override_author = 1
  [Prereqs::FromCPANfile]
  [StaticInstall]
  mode = auto
  [GithubMeta]
  issues = 1
  [Git::Contributors]

CONFIGURING
By using the PluginRemover or Config::Slicer role options, the "[@Starter]" bundle's included plugins can be customized as desired. Here are some examples:

  GatherDir
If the distribution is using git source control, it is often helpful to replace the default [GatherDir] plugin with [Git::GatherDir]. (Note: The [@Starter::Git] variant of this bundle uses "[Git::GatherDir]" by default.)

  [Git::GatherDir]
  [@Starter]
  -remove = GatherDir

The included [GatherDir] plugin can alternatively be configured directly. (See "CONFIGURATION SYNTAX" in Config::MVP::Slicer for an explanation of the subscripts for slicing array attributes.)

  [@Starter]
  GatherDir.include_dotfiles = 1
  GatherDir.exclude_filename[0] = foo_bar.txt
  GatherDir.prune_directory[] = ^temp

  Readme
The [Pod2Readme] or [ReadmeAnyFromPod] plugin (depending on bundle revision) 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 in order to generate a non-plaintext README in addition, [ReadmeAnyFromPod] can simply be used separately.

  [@Starter]
  revision = 2
  Pod2Readme.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!
  phase = release ; avoid changing files in the root with dzil build or dzil test
  [Regenerate::AfterReleasers] ; allows regenerating with dzil regenerate
  plugin = Pod_Readme

Alternatively, you can remove the default README plugin to ship a manually maintained file, or generate one with another plugin such as [Readme::Brief].

  [Readme::Brief]
  [@Starter]
  revision = 2
  -remove = Pod2Readme

  MetaNoIndex
The distribution may include additional files or directories that should not have their contents 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] = bacon

  MetaProvides
The [MetaProvides::Package] plugin will use the distribution's version (as set in dist.ini or by a plugin) as the version of each module when populating the "provides" metadata by default. If the distribution does not have uniform module versions, the plugin can be configured to reflect each module's hardcoded version where available, by setting the "inherit_version" option to 0 (the default in bundle "Revision 2").

  [@Starter]
  MetaProvides::Package.inherit_version = 0 ; default in revision 2

With this option set to 0, it will use the main distribution version as a fallback for any module where a version is not found. This can also be overridden, so that if no version is found for a module, no version will be specified for it in metadata, by setting "inherit_missing" to 0 as well.

  [@Starter]
  MetaProvides::Package.inherit_version = 0
  MetaProvides::Package.inherit_missing = 0

  ExecDir
Some distributions use the script/ directory instead of bin/ (the [ExecDir] default) for executable scripts.

  [@Starter]
  ExecDir.dir = script

  Versions
When using the "managed_versions" option, the additional plugins can be directly configured in various ways to suit your versioning needs.

  [@Starter]
  revision = 3
  managed_versions = 1

  ; configuration examples
  RewriteVersion.global = 1
  BumpVersionAfterRelease.munge_makefile_pl = 0
  NextRelease.filename = ChangeLog
  NextRelease.format = %-5v %{yyyy-MM-dd}d

EXTENDING
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 the dist.ini. You can install all plugins required by a dist.ini by running "dzil authordeps --missing | cpanm" or with "dzil installdeps".

  Name
To automatically set the distribution name from the project directory name, use [NameFromDirectory].

  License and Copyright
To extract the license and copyright information from the main module documentation, and optionally set the author as well, use [LicenseFromModule].

  Changelog
To automatically add the new release version to the distribution changelog, use [NextRelease] as the "managed_versions" option does. To ensure the release has changelog entries, use [CheckChangesHasContent].

  Git
To better integrate with a git workflow, use the plugins from [@Git], as the [@Starter::Git] variant of this bundle does. 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].

Since "Revision 6" or by including [MetaMergeFile] with an earlier revision, resource metadata and other arbitrary metadata can be specified in a metamerge.json or metamerge.yml.

  Prereqs
To specify distribution prereqs in a cpanfile, use [Prereqs::FromCPANfile]. To specify prereqs in a prereqs.json or prereqs.yml, use [PrereqsFile]. To specify prereqs in dist.ini, use [Prereqs]. To automatically guess the distribution's prereqs by parsing the code, use [AutoPrereqs].

Since "Revision 6", [PrereqsFile] is enabled by default, but prereqs can still be specified with any other method.

ENVIRONMENT
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 release

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)

SEE ALSO
Dist::Zilla, Dist::Zilla::PluginBundle::Basic, Dist::Zilla::Starter, Dist::Zilla::PluginBundle::Starter::Git, Dist::Zilla::MintingProfile::Starter, Dist::Milla