Browse files

Released version 0.02

  • Loading branch information...
1 parent 26ed761 commit 2ae1973b14f5789daed5467fa2e23a3a58a1666f @ingydotnet committed Jul 15, 2012
Showing with 87 additions and 5 deletions.
  1. +1 −1 Changes
  2. +86 −4 README
View
2 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.
View
90 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 <ingy@cpan.org>

0 comments on commit 2ae1973

Please sign in to comment.