Edit October 25, 2018:
I wasn’t really correct about the immutable cons. While by default dzil acts as a giant pre-processor, there are ways to use it that minimize the differences between the code released on CPAN and the code in your repo. You can have a $VERSION in all your modules, you can have a Makefile.PL in your repo, you can have a LICENSE file. And you can do all this while still letting dzil manage these things for you. See my plugin bundle for an example of how to do this.
I’ve been playing with Dist::Zilla lately, and while I like it, I’ve also realized there’s some perhaps not-so-obvious cons to using it as well. There’s also some obvious cons, and some obvious pros.
In talking about cons, there are really two categories. Some of the cons are essential to the design of dzil. others are non-essential, and can easily be fixed in the future, given a sufficient supply of round tuits. Obviously, the essential cons are most important.
Let’s get the non-essential ones out of the way. The obvious one is that the docs are pretty minimal right now. I found that to really get what I wanted, I had to mix together cargo-culting and source diving. I still don’t understand how the heck I can make use of Pod::Weaver.
A closely related problem is that while there are lots of dzil plugins, they too are mostly poorly documented, and they’re also insufficiently flexible. A good example, is the Dist::Zilla::Plugin::PodSpellingTests plugin. Spell checking your pod is great, and I’d love to automate it as much as I can. However, if you’re doing spell checking you must include a custom dictionary that includes things like your name.
This plugin adds a wordlist that the author created in the form of a CPAN module. That’s not very useful when the wordlist module doesn’t include a word you want to whitelist. There’s no way to provide an alternate module. Of course, the real problem is that this is a terrible interface. I don’t want to release a new distro every time I add a word to my wordlist. The right way to do this is to look for a .pod-spelling file in the distro root.
Ultimately, I skipped this plugin and created my POD spelling test “by hand”.
Let’s not pick on Marcel too much. My own dzil Mercurial plugin is pretty minimal too. It works for me, but may not satisfy anyone else.
Also, dzil is slow. It uses Moose for a CLI app, which is a known-slow combination. Someone should improve Moose startup speed ;)
But as I said, these are non-essential problems, and all entirely fixable.
So what can’t be fixed?
Ultimately, using dzil to its utmost means creating a sharp divide between the source repository and released code. Dzil is in part a big ol’ pre-processor. It does things like add a
$VERSION to each module, add boilerplate to the POD, generate a LICENSE file, etc.
Of course, Perl module authors are already accustomed to this. I’m sure that most authors don’t check their META.yml files into source control and edit them by hand. Instead, they’re updated as part of the release process. Dzil just takes this several steps further.
However, some of these steps can be particularly problematic. If you allow dzil to add the
$VERSION line, that means that when you use the distro’s modules directly from the
lib directory, they have no version. This can be a problem if you’re trying to test some other module against the source repo, and that other module has a minimum version requirement.
Similarly, when you run tests with
prove, you’re testing something that isn’t quite what gets released. Don’t worry too much; when you
dzil release, it runs the tests against the post-processed code, so you’re not likely to incur bugs this way.
You can choose to not use the
$VERSION-inserting plugin, and maintain the
$VERSION manually, and dzil still has lots of other useful features. Nonetheless, this sort of issue is likely to crop up with other plugins.
So what are the pros? Ultimately, it makes maintaining modules easier. The less non-essential work I have to do in order to make a new release, the better. Also, some of the plugins do things to ensure that my releases are not broken, like checking for an update to Changes that matches the current module version, or ensuring that I have pod syntax tests as part of the release.
For someone like me, who has dozens of modules on CPAN, these time savings really add up.
Overall, I’m pretty happy with dzil, and I consider the eliminated drudgery a win, despite the hassles. I’m hoping that this entry will give people a better idea of what they’re getting into if they explore Dist::Zilla.
I also look forward to rjbs finally finishing the much-discussed configuration system overhaul so he can finally write some damn docs ;)