=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