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 = 3         ; 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 or dzil regenerate

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. If you're just getting
    started with Dist::Zilla, check out the tutorials at <http://dzil.org>.

    Migrating from "[@Basic]" is easy for most cases. Most 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 (see "CONFIGURING"). Migrating a more complex set of plugins,
    including some that interact with the additional generated files, may
    require more careful consideration.

    "[@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 release

    For a detailed overview of how this plugin bundle works, see "PHASES".

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

    For a variant of this bundle with built-in support for a git-based
    workflow, see [@Starter::Git].

    Another simple way to use Dist::Zilla is with Dist::Milla, an
    opinionated bundle that requires no configuration and performs all of
    the tasks in "EXTENDING" by default.

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

  revision
      [@Starter]
      revision = 2

    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/*' })

    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/.

  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 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 1
    Revision 1 is the default and is equivalent to using the following
    plugins:

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

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

    [MetaProvides::Package]
    [ShareDir]
    [ExecDir]

    This revision 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].

  Revision 2
    Revision 2 is similar to Revision 1, with these differences:

    * 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 3
    Revision 3 is similar to Revision 2, but additionally supports the
    "managed_versions" and "regenerate" options, and variant bundles like
    [@Starter::Git].

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. 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]
      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

  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 added 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

PHASES
    The plugins in this bundle, and any additional plugins you include in
    dist.ini, each execute code within one or more phases when a Dist::Zilla
    command such as "dzil test" is run. You can see a full listing of the
    phases used by the plugins in your dist.ini with the command "dzil
    dumpphases".

  BeforeBuild
    The distribution build consists of several phases, starting with
    -BeforeBuild. No plugins in this bundle execute during this phase by
    default.

  FileGatherer
    In the -FileGatherer phase, many plugins add files to the distribution;
    in "[@Starter]" this includes the plugins [GatherDir], [MetaYAML],
    [MetaJSON], [License], [Pod2Readme], [PodSyntaxTests],
    [Test::ReportPrereqs], [Test::Compile], [MakeMaker] (or the configured
    installer plugin), and [Manifest].

  EncodingProvider
    In the -EncodingProvider phase, a plugin may set the encoding for
    gathered files. No plugins in this bundle execute during this phase by
    default.

  FilePruner
    In the -FilePruner phase, gathered files may be excluded from the
    distribution. In "[@Starter]" this is handled by the plugins
    [PruneCruft] and [ManifestSkip].

  FileMunger
    In the -FileMunger phase, files in the distribution may be modified. In
    "[@Starter]" the plugin [Test::Compile] runs during this phase in order
    to update its test file to test all gathered modules and scripts. When
    using the "managed_versions" option, the [RewriteVersion] and
    [NextRelease] plugins also operate during this phase.

  PrereqSource
    In the -PrereqSource phase, plugins can add prerequisites to the
    distribution. In "[@Starter]" the plugins [PodSyntaxTests],
    [Test::ReportPrereqs], [Test::Compile], and [MakeMaker] (or the
    configured installer plugin) add prereqs during this phase.

  InstallTool
    In the -InstallTool phase, the installer's Makefile.PL or Build.PL is
    generated in the distribution. In "[@Starter]", [MakeMaker] or the
    configured installer plugin handles this phase.

  AfterBuild
    The -AfterBuild phase concludes the distribution build. No plugins in
    this bundle execute during this phase by default.

  BuildRunner
    The -BuildRunner phase executes the configure and build phases of the
    "Phases" in CPAN::Meta::Spec in a built distribution. In "[@Starter]",
    [MakeMaker] or the configured installer plugin handles this phase.

  TestRunner
    The -TestRunner phase executes the test phase of the "Phases" in
    CPAN::Meta::Spec. In "[@Starter]", [MakeMaker] (or the configured
    installer plugin) and [RunExtraTests] handle this phase.

  BeforeRelease
    The -BeforeRelease phase prepares a built distribution for release. In
    "[@Starter]", the plugins [TestRelease], [ConfirmRelease], and
    [UploadToCPAN] (to ensure PAUSE username and password are available)
    execute during this phase. In [@Starter::Git], the plugin [Git::Check]
    executes during this phase.

  Releaser
    The -Releaser phase releases the distribution to CPAN. In "[@Starter]",
    [UploadToCPAN] (or [FakeRelease]) handles this phase.

  AfterRelease
    The -AfterRelease phase concludes the distribution release process. No
    plugins in this bundle execute during this phase by default. When using
    the "managed_versions" option, the [NextRelease] and
    [BumpVersionAfterRelease] plugins execute during this phase. When using
    the "regenerate" option, the [CopyFilesFromRelease] plugin executes
    during this phase. In [@Starter::Git], the plugins [Git::Commit],
    [Git::Tag], and [Git::Push] execute during this phase.

  MetaProvider
    The -MetaProvider phase executes when required rather than at a specific
    time. In "[@Starter]", the [MetaConfig], [MetaProvides::Package], and
    [MetaNoIndex] plugins provide metadata in this phase.

  VersionProvider
    The -VersionProvider phase executes when required rather than at a
    specific time. No plugins in this bundle execute during this phase by
    default. When using the "managed_versions" option, the [RewriteVersion]
    plugin acts as version provider.

  ShareDir
    The -ShareDir phase executes when required rather than at a specific
    time. In "[@Starter]", the [ShareDir] plugin handles this phase.

  Regenerator
    The -Regenerator phase is a quasi-phase which executes when "dzil
    regenerate" is run. When using the "regenerate" option, the
    [Regenerate::AfterReleasers] plugin promotes [CopyFilesFromRelease] to
    also execute during this phase.

  Other
    The operation of some plugins may not neatly fit into a particular
    phase. In "[@Starter]", the [ExecDir] plugin marks a directory as
    containing executables, which can be used by installer plugins such as
    [MakeMaker].

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 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].

  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], 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].

  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)

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

