Dist::Zilla @Starter - Revision 2
I recently released revision 2 of the [@Starter] plugin bundle for Dist::Zilla. This revision brings small improvements to the default behavior, as well as the option to set a different installer plugin. In order to use the new revision, you must set the option "revision = 2" when using the bundle.
Revision 2 uses [Pod2Readme] instead of [ReadmeAnyFromPod] to generate the text README file. [ReadmeAnyFromPod] is a great and flexible plugin, but [Pod2Readme] is much simpler for the specific purpose of generating a text README. For any additional README files in other formats, I still recommend using [ReadmeAnyFromPod].
This revision also sets the option "inherit_version" in [MetaProvides::Package] to 0 by default. This makes no difference if your distribution contains uniform module versions, or for modules which have no version (they are still marked as having the distribution version unless you set "inherit_missing" to 0 as well), but if you have modules with different versions hardcoded, this will reflect that in the "provides" metadata.
The new "installer" option allows you to swap out the default [MakeMaker] installer plugin. The primary reason to do this is to use [MakeMaker::Awesome] when you need to customize portions of the generated "Makefile.PL". There is also the option to use [ModuleBuildTiny] or [ModuleBuildTiny::Fallback] if your distribution is simple enough to use Module::Build::Tiny as your installer.
I recommend upgrading to Revision 2 if you are currently using [@Starter] or [@Basic]. Check out the documentation for details, and come visit #distzilla on irc.perl.org if you have any questions or issues.
I blog about Perl.
May I advocate [Readme::Brief] instead?
Neat, hadn't seen that one. I might use it in my own bundle, but I'll have to consider whether it would be appropriate for this one.
Well, the thing is, in tarballs, the POD dump is a supremely unuseful
README. And the core Dist::Zilla [Readme] has the distinction of managing to be even more unuseful. Even the [Readme::Brief] output is not amazing… but it’s at least pointing in the general direction of useful.Of course, for GitHub ’n’ such, the POD dump is useful, since GitHub doesn’t otherwise render the docs itself. But you don’t need to involve Dist::Zilla at all for that: GitHub knows how to render POD, and accepts it as a
READMEformat, so you can just symlinklib/Foo/Bar.pm(or wherever your main documentation lives) asREADME.podat the root of your repository. Since POD ignores the start of the file up to the first POD command, Perl files are perfectly valid POD files. Obviously the POD as rendered by GitHub will be missing any boilerplate generated through Dist::Zilla (by Pod::Weaver or whatever); on the upside, changes to the docs will not require you todzil buildin order to propagate them into theREADME, nor will every change to the docs show up twice in its commit diff (once as a change to the source and once as a change to the generatedREADME).Now obviously the tarball shouldn’t contain both a [Readme::Brief]
READMEas well as aREADME.podcontaining the module source – that would be very silly. So you need to passexclude_filename = README.podto your [GatherDir] so that it won’t get picked up into the tarball.That way, you get the module docs rendered on GitHub, up-to-date automatically, but also a reasonable
READMEin the CPAN tarball.You can see the sum total of such a setup at ap/Plack-App-Hostname.
Regarding the GitHub readme, that's beyond the scope of this bundle currently, as it does not assume any source control system. I prefer to generate README.pod and copy it on release and regenerate, either way it needs to be excluded because README.pod should never be in any distribution release (it gets installed and indexed by metacpan, unfortunately). No such issue with README.md (but I prefer .pod because internal links work better).
Regarding [Readme::Brief], I considered adding it to my own bundle but I think I prefer using [InstallGuide] to generate an INSTALL for GitHub, and it's somewhat redundant with that file in the distribution. For @Starter, I may change it over in the next revision.
The great thing about Dist::Zilla is we have all of these options to serve any preference.
One other note, [ReadmeAnyFromPod] with location = root automatically excludes the generated file from the build. Though it doesn't hurt to exclude it manually as well in case you change plugins down the line.