=pod

=for comment
DO NOT EDIT. This Pod was generated by Kwim.
See http://github.com/ingydotnet/kwim-pm#readme

=encoding utf8

=head1 NAME

Zilla::Dist - Dist::Zilla Mixed Up

=head1 SYNOPSIS

    > zild setup
    > # Edit the Meta file.
    > make publish

=head1 DESCRIPTION

This module is a formalization of a Perl package directory layout and release
process that I have been evolving for some time. I use the same layout for
Bash, Ruby, Python and Node.js package publishing.

Zilla::Dist provides a Makefile and set of scripts that take a modern code
layout and transform it into something that looks like a standard old Perl
distribution. Under the hood C<zild> generates everything that Dist::Zilla
wants and lets C<dzil> do the heavy lifting, but you never need to interact
with C<Dist::Zilla> stuff directly.

=head2 Directory Layout

A fully stacked top level CPAN package repository might look like this:

    Changes         # History in YAML
    Makefile        # Automation of test, dist, publish, etc
    Meta            # Meta info for all metadata needs (including dzil)
    ReadMe.pod      # Generated from `doc/Module.kwim`
    bin/            # Scripts
    doc/            # Kwim docs
    eg/             # Examples
    lib/            # Perl `.pm` code
    share/          # Shared files
    test/           # Test suite

Note a few things:

=over

=item * Sane / readable names

=item * Directories are lowercase / never plural

=item * Files are TitleCase

=item * No file extensions (if possible)

=item * No extra meta files like C<dist.ini>, C<.travis.yml>, C<bower.json> etc

=back

These are the I<best of> from all the package systems I've used. They make me
happy, and not tied to poor legacy standards.

=head2 Zilla::Dist

Zilla::Dist provides a Makefile to do everything. You get a new Makefile with:

    > zild setup

And you can refresh it later with:

    > make update

The Makefile has these targets:

=over

=item C<make test>

Use C<prove -lv test>

=item C<make install>

Do a C<dzil> install.

=item C<make doc>

Make the C<ReadMe.pod> and other stuff.

=item C<make cpan>

Turn repo into a C<Dist::Zilla> ready subdirectory called C<./cpan/>. This
directory has a C<dist.ini> file.

=item C<make dist>

Basically the same as C<make cpan; cd cpan; dzil build>.

=item C<make distdir>

Unzip the dist, for inspection.

=item C<make publish>

Have C<dzil> build a dist, then C<cpan-upload> it.

=item C<make publish-dryrun>

Yep.

=item C<make upgrade>

Upgrade the L<Zilla::Dist> C<Makefile>.

=item C<make help>

Show documentation for B<all> targets.

=back

=head1 RATIONALE RANTING

I've published a lot of I<packages> in a lot of programming languages. I like
taking the best ideas and spreading them around. I like reusing ideas and code
and tools as much as possible between these packages.

I trust dzil to DTRT with regard to the CPAN release process. I use almost the
exact same C<dist.ini> for some 20 CPAN packages that I've converted so far.

I don't like cluttered repos and adding new I<metadata> files for each new
tool that needs one. The C<dist.ini> file is not bad, but I can generate it
from metadata easily. So I do.

As much as these great new ideas differ from the norm, I want my CPAN
publishings to be normal to normal mongers (if there's such a thing). The
C<make publish> process does just that. End users would have to look hard to
know this wasn't a "normal" dzil release.

I'm packaging this packaging process as L<Zilla::Dist> for others to use. It's
also a decent example of a CPAN package packaged with itself.

=head1 USAGE

Start by running:

    zild setup

and you'll get a C<Makefile> and a C<Meta> file template. You need to
customize the C<Meta> file and leave the C<Makefile> alone.

To do a release, just set the C<version> in the Meta file and add a C<Changes>
section using the same version. Then run:

    make publish

This will:

=over

=item * Make sure things are ready for release.

=item * Make a dzil ready directory of your stuff called C<./cpan/>.

=item * Call C<dzil build>.

=item * Call C<cpan-upload> to send the dist to CPAN.

=item * Tag the git repo with the version string.

=item * C<git push> the repo and tag upstream.

=back

=head1 NOTES

Unlike C<dzil>, the only C<zild> command you ever use is C<zild setup> to
get the Zilla::Dist C<Makefile>. After that, all Zilla::Dist commands are
C<make> targets.

Some of the tools in Zilla::Dist are Bash, some are Perl. I'm doing a lot in
the area of Bash Package packaging. See L<http://bpan.org>.

I use the term C<Package> where CPAN people have used the term
C<Distribution>. Perl is the only language (in my packaging experience) to do
so.

The name C<t/> is another outlier. The most common is C<test/> followed by
C<tests/>.

I don't like plural directory names. Try singular. I think you'll like it too.

ALLCAPSFILENAMES ARE TOO LOUD! ChillOut.

=head1 SEE ALSO

=over

=item * L<Dist::Zilla>

=back

=head2 Modules Published to CPAN w/ `zild`

=over

=item * L<https://github.com/ingydotnet/zilla-dist-pm> !!

=item * L<https://github.com/ingydotnet/pegex-pm>

=item * L<https://github.com/ingydotnet/testml-pm>

=item * L<https://github.com/ingydotnet/kwim-pm>

=item * L<https://github.com/ingydotnet/file-share-pm>

=back

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2014. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
