NAME

       Alt - Alternate Module Implementations

SYNOPSIS

           PERL_ALT_INSTALL=OVERWRITE 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:

           PERL_ALT_INSTALL=OVERWRITE 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.

       Makefile.PL Changes
           Due to experience with <http://cpantesters.org/> problems, it is important to make  your  Alt  module
           not  install  without  explicit  direction.  You  can  accomplish  this easily in a Makefile.PL, with
           something like this:

               my $alt = $ENV{PERL_ALT_INSTALL} || '';
               $WriteMakefileArgs{DESTDIR} =
                 $alt ? $alt eq 'OVERWRITE' ? '' : $alt : 'no-install-alt';

           Similar techniques should be available for other module release frameworks.

       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:

               PERL_ALT_INSTALL=OVERWRITE 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 <ingy@cpan.org>

COPYRIGHT

       Copyright 2012-2014. Ingy döt Net.

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

perl v5.36.0                                       2022-11-27                                           Alt(3pm)