# ABSTRACT: What Pinto is, and how to use it
# PODNAME: Pinto::Manual

#------------------------------------------------------------------------------

our $VERSION = '0.037'; # VERSION

#------------------------------------------------------------------------------


__END__
=pod

=for :stopwords Jeffrey Ryan Thalhammer Imaginative Software Systems

=head1 NAME

Pinto::Manual - What Pinto is, and how to use it

=head1 VERSION

version 0.037

=head1 DESCRIPTION

This document is an overview of the L<Pinto> tool suite, and a general
guide for using L<Pinto> in the real world.  It is a work-in-progress,
so feel free to send suggestions to the author.

=head1 GOALS

Pinto has two primary goals.  First, Pinto seeks to address the
problem of instability in the CPAN mirrors.  Distributions are
constantly added and removed from the CPAN, so if you use it to build
a system or application, you may not get the same result twice.
Second, Pinto seeks to enable developers to use the CPAN toolchain for
building, testing, and dependency management of their own local
software, even if they never plan to release it to the CPAN.

Pinto accomplishes these goals by providing a suite of tools for
creating and managing your own CPAN-like repositories.  These
repositories can contain any distributions you like, and can be used
with the standard CPAN toolchain.

=head1 PRIOR ART

The idea of a private CPAN is not new.  Randal Schwartz presented
L<the idea|http://www.stonehenge.com/merlyn/LinuxMag/col42.html> back
in 2002.  Subsequently, modules like L<CPAN::Site> and L<CPAN::Mini>
were released.  More recently, L<OrePAN> and L<MyCPAN::App::DPAN> have
emerged as well.

Over the last few years, I personally used various combinations of those
modules to create private CPAN repositories at several organizations.
But they always required some wrapping and/or glue to make them usable
in the development cycle.  And none of them seemed to be designed for
extension.

I wanted a suite of tools that would work out-of-the-box, and would
accommodate a fairly wide range of use cases. Hence, L<Pinto> was
born.

=head1

=head1 COMPONENTS

The L<Pinto> suite consists of a core set of libraries and three
command line utilities.  Each of these utilities ships in a separate
distribution, so you don't have to install the whole kit if you're
only going to use a subset of the L<Pinto> suite.  However, you can
install L<Task::Pinto> if you'd like to get everything in one shot.

=head1 pinto-admin

L<pinto-admin> is a utility for creating and managing a Pinto
repository.  It supports the core operations of adding and removing
local distributions, as well as mirroring and importing foreign
distributions from other repositories.

=head2 pinto-server

L<pinto-server> provides a web service interface to your Pinto
repository.  This allows multiple (possibly remote) developers to
manage a central repository.  L<pinto-server> also functions as the
backend server to installer clients like L<cpan>, L<cpanp>, and
L<cpanm>.

=head2 pinto-remote

L<pinto-remote> is a utility for interacting with a remote Pinto
repository (via L<pinto-server>).  It provides a subset of the
operations supported by L<pinto-admin>.

=head1 USE CASES

All use cases revolve around the basic functions of adding and
removing distributions from the repository, but there are differences
in how you select and obtain those distributions.  I have used Pinto
(or can imagine using it) in the following scenarios:

=head2 SNAPSHOT OF CPAN MIRROR

You can use Pinto to create a stable snapshot of a CPAN mirror.  This
can easily be done with the C<mirror> command.

  $> pinto-admin -r /my/cpan create
  $> pinto-admin -r /my/cpan mirror

This creates a repository that contains the latest versions of all
packages on the CPAN (this may take several hours the first time you
do it).  Now, when you point your installer client at F</my/cpan> you
can now build your dependency stack and get the same result over and
over.

=head2 UPGRADING THE ENTIRE SNAPSHOT

Any time you want to upgrade to the latest version of all your
dependencies, you can run the mirror command again (it will be much
faster now).  But let's suppose that the new C<Foo-2.0> package breaks
your application.  You can remove its distribution by using the
C<remove> command like so:

  $> pinto-admin -r /my/cpan remove A/AU/AUTHOR/Foo-2.0.tar.gz

Now, when you build your dependency stack, you'll get C<Foo-1.0> (or
whatever version you had before), and all your other dependencies will
be the latest ones available.

=head2 UPGRADING SELECTED PACKAGES

Suppose you just want to upgrade package L<Bar> to version 3.0, which
was just released to the CPAN.  You can do that with the C<import>
command like this:

  $> pinto-admin -r /my/cpan import Bar-3.0

This will bring version 3.0 of package L<Bar> into your repository,
plus any additional dependencies that it requires.

=head2 ADDING YOUR OWN DISTRIBUTIONS

If you package your application into one or more CPAN-style
distributions, then you can also put your own code in the L<Pinto>
repository with the C<add> command:

  $> pinto-admin -r /my/cpan add /path/to/My-Dist-1.4.tar.gz

L<Pinto> will index your distribution (just like PAUSE) and add it to
the repository.  By default, L<Pinto> will also C<import> all the
dependencies that you've declared in your distribution.

Once again, you can point your installer client at F</my/cpan> to
install your distribution, and it will unwind and install all the
dependencies for you, using the L<Pinto> repository as the source.

=head2 PATCHING A CPAN DISTRIBUTION

Let's suppose that your application depends on L<Plack>, and you've
found a critical bug in it.  For whatever reason, the author of Plack
can't or won't fix the bug and you decide to patch the code yourself.
So after you've downloaded the distribution (or perhaps made a copy of
the one in your repository), patched the code and packaged it back up,
you can add it to your repository with the C<add> command:

  $> pinto-admin -r /my/cpan add ~/tmp/Plack-0.89-PATCHED.tar.gz

This is called adding a "local" distribution.  The packages in a local
distribution are always considered newer than the same package in a
"foreign" distribution.  So when clients request the "Plack" package
from your repository, they will always get your patched version, even
if the repository contains a foreign version with a higher version
number.

Eventually, the author of Plack finally fixes that bug and releases a
new distribution.  You can pull that distribution into your repository
(and the latest version of all the other distributions) by running the
C<mirror> command.  Finally, you can remove your patched version with
the C<remove> command:

  $> pinto-admin -r /my/cpan remove Plack-0.89-PATCHED.tar.gz

Clients requesting the "Plack" package will no longer get your patched
version, but will get the latest version that was pulled from the CPAN
instead.

=head1 PINTO AND THE DEVELOPMENT CYCLE

Even though *the* CPAN has been around for many years, the concept of
using CPAN-like infrastructure for private development is still
relatively novel.  So for many folks (including me), it isn't
immediately clear how to incorporate Pinto with the development cycle.

The following describes several usage scenarios for Pinto.  Some come
from my own experience, but some are just theoretical.  If you are
using Pinto (or some other variety of private CPAN) in other ways,
please let me know so that I can document it here.

=head2 USAGE STRATEGIES

Given the above use cases, I see four basic strategies for using
L<Pinto>, although I'm sure folks will probably come up with others...

=head3 Local Distributions Only

The first strategy is to use Pinto purely as a repository for local
distributions.  These distributions could be private or public, or a
mix of both.  But the repository contains only the distributions that
you explicitly add to it.

=head3 Snapshots Of The Public CPAN

The second strategy is to use Pinto as snapshot of the public CPAN.
In this strategy, your repository contains the current version of
every package indexed on a public CPAN, as-of the time you made the
snapshot.  You may choose to periodically update the snapshot.

=head3 CPAN Plus Local Distributions

The third strategy is to combine a snapshot of the public CPAN with
your own local distributions.  In this scenario, your Pinto repository
contains all of the CPAN distributions plus your local ones, and your
local ones always take precedence over those you got from the public
CPAN.

=head3 Project-specific Repository

The fourth (and probably most useful) strategy is to start with an
empty Pinto repository and organically C<add> your local distributions
and C<import> their dependencies as the project evolves over time.  This
keeps your repository small and focused.

=head1 PINTO AND TEAMS

=head1 PINTO AND DEPLOYMENT

=head1 PINTO AND VERSION CONTROL SYSTEMS

One of the major motivations behind Pinto was to integrate with
version control systems (VCS).  Changing dependencies are a frequent
cause of application failure (either in development or, gasp, in
production).  So it is natural to want a mechanism to rollback your
dependencies to a "known-good-state".  This is a natural fit for VCS.

L<Pinto> integrates with VCS by committing (and optionally tagging)
changes to your repository.  L<Pinto> does not provide any direct
mechanism for branching/merging/reverting your VCS.  Nor does L<Pinto>
know which revision of your repository is the "right" one.  It is
still up to you to figure that out.  But since everything L<Pinto>
does is always in your VCS, you should have everything you need to
solve those problems.

=head1 PINTO AND OTHER PACKAGING SYSTEMS

=head1 PINTO AND OTHER CPAN TOOLS

=head1 EXTENDING PINTO

=head1 FUTURE PLANS

=head1 AUTHOR

Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Imaginative Software Systems.

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

=cut

