view release on metacpan or  search on metacpan

lib/Alt.pod  view on Meta::CPAN

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

=encoding utf8

=head1 NAME

Alt - Alternate Module Implementations

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

=head1 SYNOPSIS

    PERL_ALT_INSTALL=OVERWRITE cpanm Alt::IO::All::Redux

=head1 DESCRIPTION

C<Alt::> is the namespace for alternate implementations of CPAN modules.

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

=head1 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.

=head1 THE SOLUTION

A module C<Foo::Bar> is distributed on CPAN as C<Foo-Bar>. It may have
submodules like C<Foo::Bar::Baz>.

To make an alternate CPAN version, leave everything exactly the same, except
distribute the new version as C<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
B<Alt>ernate implementation. If they don't like it, they can simply reinstall
the original Foo-Bar, or try some other alternate.

=head1 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:

=over

=item 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.

=item Makefile.PL Changes

Due to experience with L<http://cpantesters.org/> problems, it is important to
make your Alt module B<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.

=item Module for CPAN Indexing

You will need to provide a module like C<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';

=item no_index

It is important to use the C<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.

=item Versioning