2010 Grant Proposal: Improve Dist::Zilla


Improve Dist::Zilla's Tests, Documentation, and Structure


Ricardo Signes


[ hidden email ]

Amount Requested:



Dist::Zilla is a tool that helps Perl programmers build distributions for the CPAN. It eliminates boilerplate, handles packaging, interfaces with changelogs and version control, improves prerequisite management, and generally makes it easier to be a CPAN author. This grant will fund work to make it easier for new users to adopt Dist::Zilla and for Dist::Zilla itself to be more easily extended, maintained, and understood.

Benefits to the Perl Community

Dist::Zilla makes the CPAN better. More code can be released because the work required to do so is greatly lessened. The code that is released can be of a higher quality because more time can be spent on the code rather than the packaging. It can also improve the lives of CPAN authors in general: if you don't want to spend the time that Dist::Zilla saves you on writing more code, you can spend it on anything else you like: skiing, sleeping, or eating ice cream.

Dist::Zilla has already been adopted by dozens of authors and used to release hundreds of distributions.


Each deliverable below is also an "inch-stone."

proper logging facility

Right now, Dist::Zilla logs with "print." It has always been meant to use Log::Dispatch (via Log::Dispatchouli) but these changes need to be made, presumably before testing begins, so that the testing system can incorporate logged data.

Estimated time: one half day

reusable testing tools

Dist::Zilla and most of its plugins (both core and otherwise) are not well tested, because testing it is tedious. This could be greatly improved by writing a few test classes or mock plugins.

Estimated time: two days

extensive testing of the core

The reusable test tools will be put to use (and thus proven useful) when tests are written for all the core functionality. These tests may not be exhaustive, but they will be extensive and will be written with the goal of making contributors feel that they can trust the test suite to catch most regressions.

Estimated time: four days

simplification of the command line tool's code

Right now, a number of hookable events are defined only in the code implementing the dzil command, which too tightly couples the main class behavior to the command line tool. As much as is possible, the App::Cmd-based code for dzil will be turned into a very thin wrapper around Dist::Zilla's methods.

Estimated time: one half day

event structure for distribution creation

In other words, plugins will be able to attach more behavior to distribution creation, to create new source code repositories, start files, and so on.

Estimated time: one half day

core set of well-known FileFinder plugins

The FileFinder plugin role allows other plugins to operate on dynamically located sets of files like "all Perl modules that will be installed" or "all files marked executable." At present, there are no predefined FileFinder plugins with Dist::Zilla. By providing a few core finders with well-known names, it is easier for new third-party plugins to behave more like core plugins.

This requires writing the finders, testing them, and updating existing plugins to use them. It also must be possible for a user to override the behavior at the well-defined name.

Estimated time; one day

improved prerequisite handling

This will include improved methods for specifying versions required by allowing shorthand identifiers for the latest version of a prerequisite, or the version with which the author has tested.

(If the META.json 2.0 specification is sufficiently finalized by the time this work is approved, the core Dist::Zilla prerequisite system will be improved to match it. I am familiar with the proposed changes to META and have a plan for how to support them.)

Estimated time: one day

improvements for authoring distributions containing XS

I do not write XS code or C, but a number of users of Dist::Zilla do and have asked whether I can improve Dist::Zilla's ability to accomodate them. Florian Ragwitz has given me some ideas on how to do this, and I would like to carry out his plan so that Dist::Zilla does not discriminate against XS authors.

Estimated time: one half day

documentation: improved new user's guide

This will extend and supplement the existing Dist::Zila::Tutorial, starting from the position, "So you want to release code to the CPAN..." There will be a Pod version shipped with Dist::Zilla, but also an HTML document and slidecast or screencast to more clearly walk new users through the process.

Estimated time: four days

Project Schedule

I can begin work immediately upon receipt of first-third payment. I predict about ten or twelve Saturdays of work. I believe that work can be completed this quarter.


I'm RJBS on the CPAN. I have released or adopted hundreds of modules, and Dist::Zilla is the result of my own desire for a tool to make maintenance of CPAN distributions simpler. My previous TPF grant-supported work on Pod-munging tools was also in furtherance of making it easier to maintain CPAN distributions. That work was completed without problems and the released code has been succesfully adopted by a number of CPAN authors.


i totally support rjbs' grant.

i've been converting my modules to use dzil, and the results so far have been impressive:
- the lines of code & comments in my module repositories have shrinked quite a lot, since dzil generates so much boilerplate that i used to write by hand and record in the project repository
- i'm now able to release new versions in a breeze, allowing for more frequent releases... and of better quality, since all the tedious and error-prone work is now done for me automatically by dzil
- finally, i'm not afraid to create new distributions, knowing that i'll be able to concentrate on the code and the core problem i'm trying to solve. check: i've created around 10 new dists in the last 6 monthes, in large part thanks to dzil!

so, this was for dzil's usefulness. now, what about this grant? well, currently, dzil is really great, but is still in its infancy. i've created some dzil plugins, and contributed some patches to dzil, and the enhancements that rjbs propose will greatly ease the inner work on this module... and since more and more people are now using dzil, it makes sense to have this toolchain module as robust as eumm, test::more and others. moreover, some parts of this grant will allow beginners to get on board with dzil quite easilly.

also, rjbs has a long record of striving for utility module extraction: if sthg of general use can be made as a release of its own, rjbs will do it... for the greatest reuse of all perl authors.

finally, rjbs already showed that he delivers what he promised - and often even more. so by granting funds to this proposal, you know that you invest in sthg that will produce results, and results used by a lot of cpan authors.

in conclusion: i really wish this proposal to be approved.

-- jérôme

I've been "teetering on the edge" of using dzil for a while now but haven't made the plunge.

It's clear from Jérôme's comments, and elsewhere, that there's significant benefit from using dzil. For example "i've created around 10 new dists in the last 6 months, in large part thanks to dzil". That's clearly a significant benefit.

My problem has been finding the time to climb the learning curve. I don't want to have to read the docs for ~26 plugins to decide which to use, and how, for a simple distribution. So I cop-out and do it the old way. The barrier to entry needs to be lower for lazy people :)

For new modules I want to type in a single command giving the name of the new distribution, and perhaps a few options, and get a whole new directory tree with a 'best practices' dzil setup. Perhaps that means integrating with something like Module::Starter in some way.

The proposal suggests supplementing the existing Dist::Zila::Tutorial, starting from the position "So you want to release code to the CPAN...". Supplementing the tutorial would be great, but I think two starting positions are needed: one for people starting a new module from scratch, and another for people integrating dzil into an existing module (*cough* DBI *cough*).

Anyway, incase it's not clear, I fully support this proposal and trust rjbs to do a great job.

-- Tim.

Thanks for your support, Tim.

You mention "integrating with something like Module::Starter." For a long time, I didn't understand what people meant by this. My goal with Dist::Zilla was to eliminate the boilerplate built my Module::Starter, so the tool became redundant. As time went on, though, I got a lot of good input on the idea, including how it would be useful in many cases.

A few of the tasks above, especially "event structure for distribution creation" go toward making it easy to use the "dzil new" command as a Module::Starter-like tool, without the baggage of Module::Starter, which is pretty painful to extend (and that pain is largely my own fault, sadly).

Like Tim I haven't used Dist::Zilla but I've looked at it and the source for some of rjbs's modules and I'm impressed that it generates all the nasty boilerplate that I maintain manually.

It would be very good to get better documentation for it however, and support for XS modules.

I support this proposal.

I'm another person the list of "would like to use dzil but got hung up on the docs". In particular, I agree with Tim that some docs specifically on how to integrate dzil into an existing module are sorely needed.

All of this is to say that I support this grant.

As an aside, I think that the related Pod munging modules either need more docs, or dzil needs docs on how to use them, or some combo of the two. This is where I really got hung up on trying to use dzil last time. My main motivation was to reduce doc boilerplate but I just could not figure out how to add custom sections to the pod weaving process.

Thanks, Dave.

I agree (obviously, hence this grant!) that the documentation is sort of helter skelter right now. Dist::Zilla is unlike most of my other work, and unlike most Pod-documented libraries because almost all of its functionality comes from plugins. It's become clear that just documenting each module isn't sufficient (who wants to read 25 short man pages?) and I need to write a proper introduction and manual. I'd like to produce a Pod-based manual, but I think it is unrealistic, and that I am more likely to produce an HTML and/or PDF manual with diagrams and sidebars.

Pod::Weaver is likely to be touched upon by this documentation, but I don't think it's likely to get the same full treatment merely by virtue of the grant. On the other hand, I will have to execute the documentation of such a system, so it will be much easier for me to document Pod::Weaver after I've documented Dist::Zilla!

Leave a comment

About this Entry

This page contains a single entry by Alberto Simões published on February 6, 2010 5:00 PM.

2010 Grant Proposal: Perl Compiler was the previous entry in this blog.

2010Q1 Grant Proposal: perl core memory improvements is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.