Dist::Zilla @Starter Revision 3 - Git, versioning, and more
Tags: perl
Published: 2021-03-11 23:46:33

I've just released revision 3 of the [@Starter](https://metacpan.org/pod/Dist::Zilla::PluginBundle::Starter) plugin bundle for the Dist::Zilla CPAN distribution authoring tool. There's no changes to the base configuration from revision 2, but there are now additional options to help manage common authoring tasks using modern best practices. You must set your revision to 3 to enable these new options, as a safety measure to make sure you have a new enough version of the bundle to support them.

The `managed_versions` option is the most complex new addition. Instead of declaring a distribution version in your dist.ini or using a plugin like [Git::NextVersion] or [AutoVersion] to determine it, this option lets you version your modules like you normally would and reads the version of your main module to use as the distribution version. The versions of any other modules in the distribution are updated to match in the build or release, and after a release it's incremented in the source files. This is widely considered the least fragile and most contributor-friendly method of managing versions with Dist::Zilla currently, as your modules don't require Dist::Zilla to determine their version while testing.

The `regenerate` option makes use of a very useful quasi-phase called [-Regenerator](https://metacpan.org/pod/Dist::Zilla::Role::Regenerator) created by Kent Fredric. For each filename you specify, it copies this file from the Dist::Zilla build tree to your source tree whenever you release as well as when you run `dzil regenerate`. This can be useful for keeping generated files such as LICENSE in your git repository where they may also be important, as well as copying your Makefile.PL/Build.PL and META.json to your source tree if you wish to make it directly installable with [cpanm](https://metacpan.org/pod/cpanm) for testing or Travis CI. (Note: this method is only for testing unreleased changes, you should always install distributions from CPAN normally.)

Finally, revision 3 made it possible to release the [@Starter::Git](https://metacpan.org/pod/Dist::Zilla::PluginBundle::Starter::Git) variant bundle, which takes all of the same options as `@Starter`, and interleaves plugins appropriate to a Git workflow. [Git::GatherDir] replaces [GatherDir], as it's a simple subclass that prevents cruft from being gathered by simply gathering the files tracked in Git. This means your .gitignore can be used to exclude files from both the repository and your distribution builds. This mostly obsoletes the need for [PruneCruft] and [ManifestSkip] to clean up your distribution build, but the bundle still includes them as they don't tend to cause any problems. In addition, the bundle will check for any uncommitted changes before releasing, and after releasing commit and tag the release (as well as a separate version bump commit if you also enable managed versions), and push to your Git origin if you have one configured.

The `@Starter::Git` bundle also comes with a matching [Dist::Zilla minting profile](https://metacpan.org/pod/Dist::Zilla::MintingProfile::Starter::Git), which is similar to the `@Starter` profile but additionally adds a basic .gitignore to start you out, and initializes the new directory as a Git repository.

I hope these new options are helpful in modernizing your distribution workflow. As always, any plugins used by the bundle can be fully configured by config slicing, you can even look at the new bundle's [dist.ini](https://metacpan.org/source/DBOOK/Dist-Zilla-PluginBundle-Starter-Git-v3.0.1/dist.ini) for examples of using itself. Please stop by [#distzilla on irc.perl.org](https://kiwiirc.com/nextclient/#irc://irc.perl.org/#distzilla) if you have any questions, big or small, we are happy to help.

*Since the original publication of this post, `@Starter` and `@Starter::Git` have reached revision 5, with a few minor enhancements.*