The idea of a new/expanded Dist::Zilla tutorial has my full support. I have started using dzil some time ago and am pretty happy about that decision. Only I am still struggling with it, especially if a GitHub repository builds its package with plugins I've never heard of before, and which has a bunch of dependencies to modules (or even external tools) I've never heard of before. Quite often I find myself inspecting the plugin code to find out how to get the benefits but disable some unwanted behaviour.

I am sure you are aware of RJBS's tutorial at http://dzil.org/tutorial/start.html which has been written by someone who knows way too much about Dist::Zilla. It is concise, which is a good thing, but it lacks any hints on how to find more details about the plugins: What they actually do, how they can be configured. Often a link to the relevant CPAN would do the trick. I often considered adding stuff, but then doing that in a structured way needs more time than I ever had.

Your article, on the other hand, makes a good introductory chapter in the Comprehensive Book On Dist::Zilla. However, in my opinion it is just too long to be a tutorial. I guess that anyone who considers whether or not to start using Dist::Zilla is aware of software building and packaging. They don't need more motivation, but rather look for hints how to judge cost vs. benefits, or for a guide through the mess of available features. Here are a few questions which I'd like to see answered in an introductory article about Dist::Zilla:

• What's the scope of Dist::Zilla?
• How does it affect the workflow? For example, there are a few articles about how to make dzil distributions palatable for developers who want to contribute on GitHub without using dzil themselves. All of these are blog articles which are not maintained and get difficult to find as years go by.
• How does it compare to other build / install tools?
• What are the resources to learn more? Apart from RJBS's tutorial, the #dzil channel comes into mind, where one can learn a lot by just listening.

Thanks for the feedback. I will try to work these more practical questions into the series.

My intro actually started with the idea that “there ought to be a book.” I’m far from qualified to write such a book. But writing this intro was also a good exercise for me to cement some fundamental concepts in my mind. I will come up with a TLDR version that boils down the essence of it at some point.

I renew my original caution—which I’ll point out proved prescient—and partial objection. Dist::Zilla is for power users who already understand the concerns; users owning many modules frequently updated, not those owning a couple rarely touched. In my view, the packages cannot be made beginner friendly because they are not for beginners. I’d loved to be proved wrong.

I skimmed the guide. …I don’t really see this as helping beginners use the packages. It’s more of an apologist tract and marketing pamphlet than a guide. It will be interesting to some but at the end of reading it, no knowledge about how to use the packages is gained, only reasons why one might.

I can only speak for myself, of course, but an intro like mine would have really helped me make a clear distinction between what a module was and what a distribution was. These concepts were muddy for me. Also having some kind of general context for what I was actually trying to achieve would have helped me a great deal as well.

I have not written the guide yet. This is just the intro. I plan on doing a series of short tutorials that to get beginners up to speed on the basics of creating a distribution and how Dist::Zilla can be used to speed that process along.

an intro like mine would have really helped me make a clear distinction between what a module was and what a distribution was. These concepts were muddy for me.

I guess from the phrasing here that you are nysus in disguise. Did you read How to make a CPAN Module Distribution in the Creating and Distributing Modules tutorials section? That makes the distinction pretty clear to me.

Dist::Zilla is sorely lacking an entry-level tutorial or user guide. That's not to say that I would recommend its use for a first-time CPAN author - quite the opposite. It is the most arcane of all the module management systems and is aimed at (and IMHO only really useful for) the most prolific authors.

You can write an intro to CPAN, modules and dists if you wish but there are plenty around already. It would save you time and effort just to refer to those and instead build on them by focusing on the nuts and bolts of Dist::Zilla and how it compares/contrasts with other options.

Personally, as a prolific CPAN distribution author and someone who has written a piece of automated test software that has to deal with Dist::Zilla distributions, I'll say that your efforts are valiant, but I despise the software.

It requires so many additional pieces to be installed, it's mind-boggling.

The requirements to install a dist-zilla install reaches far beyond the requirements I demand in all of my dists, combined.

Yes, it's a fascinating piece of work, but it doesn't follow the "do one thing, and do one thing good" rule.

You've done a good job selling it, but it is a bit long-winded.

I would recommend that instead of focusing on dealing with your installer, you work on your own code instead.

My personal opinion.

-stevieb

ps, for what it's worth.

sub _dzil_shim {
    # shim for working on Dist::Zilla modules
 
    my ($self, $cmd_file) = @_;
 
    # return early if possible
 
    return if -e 'Build.PL' || -e 'Makefile.PL';
    return if ! -e 'dist.ini';
 
    my $log = $log->child('_dzil_shim');
    $log->_5("dzil dist... loading the shim");
 
    my $path_sep = $self->is_win ? ';' : ':';
 
    if (! grep {-x "$_/dzil"} split /$path_sep/, $ENV{PATH} ){
        $log->fatal(
            "this appears to be a Dist::Zilla module, but the dzil bin
+ary " .
            "can't be found\n"
        );
    }
 
    $self->{is_dzil} = 1;
 
    open my $fh, '<', 'dist.ini' or croak $!;
 
    my ($dist, $version);
 
    while (<$fh>){
        if (/${ re_brewbuild('extract_dzil_dist_name') }/){
            $dist = $1;
        }
        if (/${ re_brewbuild('extract_dzil_dist_version') }/){
            $version = $1;
        }
        last if $dist && $version;
    }
 
    $log->_7("running dzil commands: 'dzil authordeps --missing | cpan
+m', " .
             "'dzil build'"
     );
 
    `dzil authordeps --missing | cpanm`;
    `dzil clean`;
    `dzil build`;
 
    my $dir = "$dist-$version";
    copy $cmd_file, $dir if defined $cmd_file;
    chdir $dir;
    $log->_7("entered $dir directory");
}
sub _dzil_unshim {
    # unshim after doing dzil work
 
    my $self = shift;
 
    my $log = $log->child('_dzil_unshim');
 
    if (! $self->{is_dzil}){
        $log->_7("not a dzil distribution; nothing to do");
        return;
    }
 
    $log->_5("removing dzil shim");
 
    $self->{is_dzil} = 0;
    chdir '..';
    $log->_7("changed to '..' dir");
}
[download]

Everything you say could be true. I'm not qualified to say but I will definitely take it into consideration. I still find personal value in trying to unravel how this system of modules works. I will definitely try to address your concerns and explain the downside of Dist::Zilla as I learn more about them. Thanks!

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks