NAME
    Alt - Alternate Module Implementations

SYNOPSIS
        cpanm Alt::IO::All::Redux

DESCRIPTION
    "Alt::" is the namespace for alternate implementations of CPAN modules.

    The purpose of the Alt module is to provide documentation explaining the
    Alt concept, how it works, and guidelines for using it well.

THE PROBLEM
    For a given piece of software, CPAN only allows for one implementation
    of a given module/distribution name.

    GitHub on the other hand, is not limited this way. Any author can make a
    fork, since GitHub repos are namespaced by author id.

    On CPAN, even the author(s) of the module in question is limited by
    this, as they cannot release newer or older forks of their code, without
    introducing a new name.

THE SOLUTION
    A module "Foo::Bar" is distributed on CPAN as "Foo-Bar". It may have
    submodules like "Foo::Bar::Baz".

    To make an alternate CPAN version, leave everything exactly the same,
    except distribute the new version as "Alt-Foo-Bar-AltIdentifier".

    When a user installs your module like so:

        cpanm Alt::Foo::Bar::better

    they will get your version of the Foo::Bar framework (Foo::Bar,
    Foo::Bar::Baz).

    Obviously, this completely overlays the old Foo::Bar install, but that's
    the whole idea. The user isn't surprised by this because they just asked
    for an Alternate implementation. If they don't like it, they can simply
    reinstall the original Foo-Bar, or try some other alternate.

ALT BEST PRACTICES
    This idea is new, and the details should be sorted out through proper
    discussions. Pull requests welcome.

    Here are the basic guidelines for best using the Alt namespace:

    Name Creation
        Names for alternate modules should be minted like this:

            "Alt-$Original_Dist_Name-$phrase"

        For instance, if MSTROUT wants to make an alternate IO-All
        distribution to make it even more crack fueled, he might call it:

            Alt-IO-All-crackfueled

        He might also just call it:

            Alt-IO-All-MSTROUT

        By having 'Alt' at the start, it guarantees that it does not mess
        with future IO::All development. The "phrase" at the end can be
        anything unique to CPAN, but should describe the spirit of the
        alternate. If the alternate is meant to be short-lived, it can just
        be the author's CPAN id.

    Module for CPAN Indexing
        You will need to provide a module like "Alt::IO::All::MSTROUT" so
        that CPAN will index something that can cause your distribution to
        get installed by people:

            cpanm Alt::IO::All::MSTROUT

        Since you are adding this module, you should add some doc to it
        explaining your alternate version's improvements.

        The Alt:: module can be as simple as this:

            package Alt::IO::All::MSTROUT;
            our $VERSION = '0.01';

    no_index
        It is important to use the "no_index" directive on the modules you
        are providing an alternates for. This is especially important if you
        are the author of the original, as PAUSE will reindex CPAN to your
        Alt- version which defeats the purpose. Even if you are not the same
        author, it will make your index reports not show failures.

    Versioning
        It is not enough to not index the new modules. We have seen cases
        where smoke testing machines have installed Alt modules, and then
        gotten the wrong dependencies for something else later on. You
        should set the $VERSION as low as possible for the modules you are
        providing alternates for.

        The easiest way to do that is to not have any $VERSION at all for
        the alternates. (Just have a $VERSION for your "Alt::*" module).

        NOTE: If someone deps on version '0' of the module you are Alting,
        even no $VERSION will satisfy that. This is only a possible problem
        under specific situations:

        1.  On a machine that is installing random modules (like a
            smoketesting box)

        2.  A module deps on VERSION 0 of something

        3.  That something is Alted

        4.  The Alt VERSION got installed prior

        5.  The Alt VERSION is broken

    "use" the Alt
        You should add this line to your alternate modules:

            use Alt::IO::All::MSTROUT;

        That way the Alt:: module gets loaded any time you "use IO::All"
        (with the alternate version installed). This gives debugging clues
        since the Alt:: module is now in %INC.

    Other Concerns
        If you have em, I(ngy) would like to know them. Discuss on
        #toolchain on irc.perl.org for now.

WHENCE ALT?
    The Alt- concept was thought up by Ingy as he tried to figure out how to
    revamp the somewhat popular IO::All and YAML.pm modules. Alternates can
    now be released and alpha/beta tested, while the originals remain
    stable.

    When Alt-IO-All-new is "community approved" it can replace IO-All. If
    people want the old code, they can can install Alt-IO-All-old.

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

COPYRIGHT
    Copyright 2012-2014. Ingy döt Net.

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