NAME
   Dist::Zilla::PluginBundle::Starter - A minimal Dist::Zilla plugin bundle

SYNOPSIS
     ; dist.ini
     name    = My-Cool-Distribution
     author  = Example Jones <[email protected]>
     license = Perl_5
     copyright_holder = Example Jones
     copyright_year   = 2017
     version = 0.001

     [@Starter]           ; all that is needed to start
     revision = 5         ; 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 = 5         ; 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 = 5

   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

   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.

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

 Revision 4
   Revision 4 is similar to Revision 3, but removes 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 5
   Revision 5 is similar to Revision 4, with these differences:

   * 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".

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

 Just the basics
     name    = Acme-Foo
     author  = Jane Doe <[email protected]>
     license = Artistic_2_0
     copyright_holder = Jane Doe
     copyright_year   = 2019
     version = 1.00

     [@Starter]
     revision = 5

     [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 <[email protected]>
     license = Artistic_2_0
     copyright_holder = Jane Doe
     copyright_year   = 2019

     [@Starter::Git]
     revision = 5
     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 = 5
     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].

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

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 <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.