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

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

    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.

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

REVISIONS

    The [@Starter] plugin bundle currently includes only one revision.

 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]

    [ShareDir]

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

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

 Readme

    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 in order to generate a non-plaintext README in
    addition, the plugin can simply be used 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 = script

 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 use
    each module's hardcoded version.

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

    With this option set, 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 no version will be specified for these modules in
    the metadata.

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

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.

 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

    A common approach to maintaining versions in Dist::Zilla-managed
    distributions is to automatically extract the distribution's version
    from the main module, maintain uniform module versions, and bump the
    version after a release. This can be accomplished with either
    [RewriteVersion] with [BumpVersionAfterRelease], or [VersionFromModule]
    with [ReversionOnRelease]. Don't mix these two methods!

 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)

SEE ALSO

    Dist::Zilla, Dist::Zilla::PluginBundle::Basic,
    Dist::Zilla::MintingProfile::Starter

