2010 Grant Proposal: Improve Dist::Zilla
Sat, 06-Feb-2010 by
Alberto Simões
edit post
<![CDATA[
<h1>Improve Dist::Zilla's Tests, Documentation, and Structure</h1>
<dl>
<dt><strong>Name:</strong></dt>
<dd>
<p>Ricardo Signes</p>
</dd>
<dt><strong>Email:</strong></dt>
<dd>
<p><code>[ hidden email ]</code></p>
</dd>
<dt><strong>Amount Requested:</strong></dt>
<dd>
<p>$2000</p>
</dd>
</dl>
<p>
</p>
<h2>Synopsis</h2>
<p>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.</p>
<h2>Benefits to the Perl Community</h2>
<p>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.</p>
<p>Dist::Zilla has already been adopted by dozens of authors and used to release
hundreds of distributions.</p>
<p>
</p>
<h2>Deliverables</h2>
<p>Each deliverable below is also an "inch-stone."</p>
<p>
</p>
<h3>proper logging facility</h3>
<p>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.</p>
<p>Estimated time: one half day</p>
<p>
</p>
<h3>reusable testing tools</h3>
<p>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.</p>
<p>Estimated time: two days</p>
<p>
</p>
<h3>extensive testing of the core</h3>
<p>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.</p>
<p>Estimated time: four days</p>
<p>
</p>
<h3>simplification of the command line tool's code</h3>
<p>Right now, a number of hookable events are defined only in the code
implementing the <em class="file">dzil</em> 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 <em class="file">dzil</em> will be turned into a very thin wrapper around Dist::Zilla's
methods.</p>
<p>Estimated time: one half day</p>
<p>
</p>
<h3>event structure for distribution creation</h3>
<p>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.</p>
<p>Estimated time: one half day</p>
<p>
</p>
<h3>core set of well-known FileFinder plugins</h3>
<p>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.</p>
<p>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.</p>
<p>Estimated time; one day</p>
<p>
</p>
<h3>improved prerequisite handling</h3>
<p>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.</p>
<p>(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.)</p>
<p>Estimated time: one day</p>
<p>
</p>
<h3>improvements for authoring distributions containing XS</h3>
<p>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.</p>
<p>Estimated time: one half day</p>
<p>
</p>
<h3>documentation: improved new user's guide</h3>
<p>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.</p>
<p>Estimated time: four days</p>
<p>
</p>
<h2>Project Schedule</h2>
<p>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.</p>
<p>
</p>
<h2>Bio</h2>
<p>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.</p>
]]>
Comments (6)
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!
