From 2ae1973b14f5789daed5467fa2e23a3a58a1666f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ingy=20d=C3=B6t=20Net?= Date: Sun, 15 Jul 2012 15:13:12 -0700 Subject: [PATCH] Released version 0.02 --- Changes | 2 +- README | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 87 insertions(+), 5 deletions(-) diff --git a/Changes b/Changes index c67ed90..7f4f531 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ --- version: 0.02 -date: +date: Sun Jul 15 15:12:46 PDT 2012 changes: - Wrote the first real doc revision. diff --git a/README b/README index d05a3cd..a9cf15a 100644 --- a/README +++ b/README @@ -2,14 +2,96 @@ NAME Alt - Alternate Module Implementations SYNOPSIS - cpanm Alt::IO::All::mst + cpanm Alt::IO::All::crackfueled DESCRIPTION "Alt::" is the namespace for alternate implementations of CPAN modules. - This documentation is intended to explain this concept, how it works, - and guidelines for using it well. - ... documentation in progress ... + 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. + +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. + +GUIDELINES + This idea is new, and the details should be sorted out through proper + discussions. Pull requests welcome. + + Here are the basic guidelines for 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. + + Versioning + It's not yet clear what kinds of versioning issues will come into + play. + + Other Concerns + If you have em, I(ngy) would like to know them. Discuss on + #toolchain on irc.perl.org for now. AUTHOR Ingy döt Net