Ricardo Signes - Improve Dist::Zilla's Tests, Documentation, and Structure

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

Name: Ricardo Signes

Grant Manager: Ricardo Signes

Duration: two or three months

Started: March, 2010

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.