PuppetShop
===========

This documention describes a web-based application to facilitate the
sharing of Puppet recipes, with the possibility of using it to share
non-Puppet code eventually.

Basics
------
The primary feature is that recipe developers can register modules,
and then associate branches with that module (with the default branch
probably being called 'trunk').  Users of the site will be able to
use the web interface to find a module and/or branch, and then use
the SCM that the branch is in to retrieve the branch they want.

Terminology
-----------

:authoritative: The repository from which all changes descend.
:branch: A single repository containing a version of the module.
:module: A named chunk of functionality.

Critical Features
-----------------

Separation between module and branch
''''''''''''''''''''''''''''''''''''
The separation between module and branch is critical, as branches
will often be published by authors other than the module author.
This will encourage more people to work on and publish versions of a
branch.

Distributed Source Control
''''''''''''''''''''''''''
The branches should all be maintained in a branch of a distributed
source control system, like Git_, Darcs_ or Mercurial_.  This will
make it easy to collaborate, as any module user can maintain a
parallel branch with their own customizations and modifications.
This is critical because many of these recipes will only have
partial functionality for a given site, such as support for Debian
but not Fedora.

Self-hosted Branches
''''''''''''''''''''
Each published branch must have its authoritative repository hosted
by the branch author.  This makes it easy for the branch maintainers
to update their code, without ever interacting with our web site.  The
web site will regularly pull changes from the authoritative branch
(probably daily), possibly with an option for the module author to
trigger an update.

Other Important Details
-----------------------

- *Licensing*: Initially, branches will all need some sort of open
  source license, as they will all be free with no means to charge.
  Even so, modules will need to register a license at registration
  time, as the different open-source licenses are drastically
  different.

- *Text Format*: Each module will have a description, written in
  `Restructured Text`_.  It is likely that this description will be
  pulled from the 'trunk' branch, else it would require that the
  module maintainer spend unnecessary time on the web site.  Ruby does
  not yet have an RST parser, so we will need to convert the file from
  RST to HTML when it changes, rather than doing it dynamically, but
  this should be no problem.

- *Subscriptions*: Branch users need some way to specify that they're
  interested in specific modules or branches, so it's easy for them to
  visit the site to see if there are any updates.

- *Naming*: I have no idea what to call the site.  I've been thinking
  somewhere between a marketplace and a puppet shop, but that doesn't
  equal a name.

Looking To the Future
---------------------

There are many things we should at least keep in mind during the
development of this web site:

- *Hosted Branches*:  It would be nice if we could be the
  authoritative source for branches, but this will require the use of
  a dSCM that supports a server or will require branch maintainers
  have SSH access.

- *Non-Puppet Modules*: If we develop this site correctly, then it
  could reasonable be used for non-Puppet code, such as very small
  projects or even stand-alone scripts.

- *Non-executable Content*: There is a lot of content in this space
  (system administration and maintenance), such as tutorials, and no
  good place for it.  If our application made it easy to publish and
  udpate these documents, then it could begin to become a central
  meeting place for sysadmins, or generally tech stuff.

- *Reputation Systems*: It would be especially great if both branch
  maintainers and the branches themselves could have some sort of
  reputation system, it would make finding good modules much easier.
  It would even provide a way for us to convert ownership:  If a
  non-trunk branch has a significantly higher reputation than the
  trunk branch, one could reasonably change ownership.

- *Commercial Content*: Many people have great content but are
  unwilling to give it away.  If we could enable a way to charge
  people for access to content, taking some percentage and giving the
  rest to the branch (and/or module?) author, then the web site could
  conceivably be quite profitable.

- *Corporate Islands*: Many companies have needs that closely approach
  the goals of this web site, but with collaboration restricted to the
  company's employees and partners.  We could possibly provide
  software-as-a-service to these companies, making it easy for them to
  publish and share their information internally, probably making it
  possible for them to subscribe to external modules.

.. _restructured text: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _git: http://git.or.cz/
.. _mercurial: http://www.selenic.com/mercurial/
.. _darcs: http://darcs.net/