Welcome to puritan
==================
:Author: Michael Stone <michael@laptop.org>
:Date: March 07, 2008

Puritan is an MIT-licensed disk-image compiler for constructing OLPC disk
images from sources including RPM repositories and build-stream descriptions.

It is loosely derived from a similar tool, Pilgrim, written by David Zeuthen,
John Palmieri, C. Scott Ananian, Dennis Gilmore, and Michael Stone and is being
considered to replace Pilgrim, along with livecd-tools.

In the puritan framework, each and every compilation (build configuration) is
described by a git commit and can be authoritatively identified by a git tag
pointing to that commit. Relationships between compilations are recorded in the
git version graph.

In the present layout, changes that are suitable for all builds should be
included in the 'compiler' puritan branch. Build-specific configuration and
instructions should go in other branches and these other branches should be
regularly rebased on top of 'compiler' in order to produce highly readable
history graphs.

If desired, the RPM and activity sources for each build can be archived in a
separate git repository and can be strongly versioned along with the
compilation that used them by including the sources as a git submodule in the
compilation commit.

The raw dependencies of puritan consist of:

    git-core python-2.5 mock

Mock is used to construct a build root with packages described by the
compilation's bootstrap and dependencies files.

The Puritan UI is invoked by installing a puritan rpm (built from the ui branch)

    wget -O puritan.rpm http://teach.laptop.org/~mstone/releases/RPMS/noarch/puritan-0.2-1.olpc2.noarch.rpm
    sudo rpm -Uvh puritan.rpm

then by checking out a 'puritan compilation' to be run by /usr/bin/puritan

    $(git clone git://dev.laptop.org/users/mstone/puritan compilation; cd compilation; git checkout devel_jffs2)
    puritan ./compilation HEAD ./results

Finally, please help improve puritan by

    * making it work on your platform
    * fixing the devel_ext3 compilation
    * adding some reasonable package or buildroot caching system so that it
      runs faster without impairing build repeatability
    * improving the UI with commands for manipulating compilations, or for
      diffing builds, or for profiling compilations, or ... 

Contributing
------------

The public fora that I frequent include:

  devel@lists.laptop.org
  #olpc on irc.freenode.org as 'm_stone'
  http://dev.laptop.org, user 'mstone'

My source tree is available at:

  http://dev.laptop.org/git/users/mstone/puritan            (browse)
  git://dev.laptop.org/users/mstone/puritan                 (clone)
  git+ssh://$username@dev.laptop.org/git/$username/puritan  (commit)

Since I use a distributed development model, you can send me your work in
several ways. I am happy to receive:

  1) a link to your clone of the puritan repository and a summary of what
     you'd like me to examine in it

  2) an emailed patch, preferably indicating the commit to which the patch
     should be applied

  3) general comments, questions, and reviews in any medium

