The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
INGY / Zilla-Dist-0.0.192 / lib / Zilla / Dist.pod 
=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.39.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

Zilla::Dist - Dist::Zilla Mixed Up

=for html
<a href="https://travis-ci.org/ingydotnet/zilla-dist-pm"><img src="https://travis-ci.org/ingydotnet/zilla-dist-pm.png" alt="zilla-dist-pm"></a>

=head1 VERSION

This document describes L<Zilla::Dist> version B<0.0.192>.

=head1 SYNOPSIS

    > zild Meta
    > # Edit the Meta file.
    > zild release

=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
    Contributing    # A generated instruction file for contributing
    Meta            # Meta info for all metadata needs (including dzil)
    ReadMe.pod      # Generated from `doc/Module.swim`
    .travis.yml     # Travis file (generated)
    bin/            # Scripts
    doc/            # Swim docs
    ext/            # External repos (subrepos)
    eg/             # Examples
    lib/            # Perl `.pm` code
    pkg/            # Packaging related files
    note/           # Project notes, todo lists, ideas, specs, etc
    share/          # Shared files to distribute
    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 uses a Makefile to do everything, but you never see it. You run
commands like:

    zild make test

Run C<zild make help> to get a list of all the targets.

The most common targets don't require you to type C<make>. For instance, you
can simply:

    zild test

Here are the most important targets:

=over

=item C<zild release>

Build the dist, then C<cpan-upload> it.

=item C<zild test>

Run the test suite.

=item C<zild install>

Build and install the software. Same as install from CPAN.

=item C<zild update>

Rebuild the ReadMe.pod and other generated files.

=item C<zild prereqs>

Install the prereqs from CPAN that are listed in the C<Meta> file's
C<requires:> field.

=item C<zild cpan>

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

=item C<zild dist>

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

=back

=head1 USAGE

Start by running:

    cp `zild sharedir`/Meta .

and you'll get a C<Meta> file template. You need to customize the C<Meta> file
with information specific to your project.

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

    zild release

This will:

=over

=item * Make sure things are ready for release.

=item * Update the modules with C<$VERSION> to the new version.

=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

=head2 Release in Depth

This section lists all the things that actually happen during the C<zild
release> step.

I<…to be completed…>

=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 50 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<zild release> 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 NOTES

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.

=head2 Commiting Generated Code/Files

People think that committing generated code/files is a bad idea and in general
I concur, but there are exceptions.

Sometimes tools like Travis-CI require you to commit a config file.
Zilla::Dist generates these files from metadata, which is a whole lot easier
than maintaining them yourself, but you end up commiting generated code.

The C<dist.ini> file is only needed locally, however, during dist build time,
so no need to commit that.

In general, when an external tool requires files, and it's easiest to generate
those files, it's OK to commit generated code.

=head2 Modules Published to CPAN w/ C<zild>

=over

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

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

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

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

=item * L<https://github.com/ingydotnet/alt-sex-ingy-pm>

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

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

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

=item * L<https://github.com/ingydotnet/convert-base32-crockford-pm>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=item * L<https://github.com/ingydotnet/module-install-ackxxx-pm>

=item * L<https://github.com/ingydotnet/module-install-manifestskip-pm>

=item * L<https://github.com/ingydotnet/module-install-requireslist-pm>

=item * L<https://github.com/ingydotnet/module-install-versioncheck-pm>

=item * L<https://github.com/ingydotnet/module-manifest-skip-pm>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=item * L<https://github.com/ingydotnet/plack-middleware-cache-pm>

=item * L<https://github.com/ingydotnet/plack-middleware-proxymap-pm>

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

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

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

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

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

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

=item * L<https://github.com/ingydotnet/swim-plugin-badge-pm>

=item * L<https://github.com/ingydotnet/swim-plugin-cpan-pm>

=item * L<https://github.com/ingydotnet/template-toolkit-simple-pm>

=item * L<https://github.com/ingydotnet/template-plugin-yamlval-pm>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=back

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright 2014-2015. 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