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 have it be Moo-based, he might call it:

           Alt-IO-All-Moo

       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 important to not declare a $VERSION in any of the modules that
       you are providing alternates for. This will help ensure that your
       alternate module does not satisfy the version requirements for
       something that wants the real module.

       If you want to depend on the alternate versions, then set the
       dependency on the "Alt::" module.

       NOTE: If you provide an alternate Foo::Bar (with no VERSION) it will
       satisfy the version requirements for someone who requires "Foo::Bar
       => 0". In a sense, depending on version 0 means that alternates are
       OK.

   "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 <[email protected]>

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

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.