Add anatomy of a repository docs.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/doc/create.rst b/doc/create.rst
index 352cc63aa4e9118eb3c49496f21eb6af4857a4ac..c040f5513c7849da2f9abd8a2653dcb28df55f2c 100644 (file)
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -180,29 +180,6 @@ can also create a pristine branch::
 
     git branch pristine
 
 
     git branch pristine
 

-.. todo::
-
-    The following text and graph should be put in a more general overview of
-    the topology of Wizard git repositories.
-
-From the point of view of the pristine branch pointer, history should be a
-straight-forward progression of versions.  Once you have more versions,
-it will look something like:
-
-.. digraph:: pristine_dag
-
-    rankdir=LR
-    node [shape=square]
-    subgraph cluster_pristine {
-        a -> b -> c
-        a [label="1.0"]
-        b [label="1.1"]
-        c [label="2.0"]
-        label = "pristine"
-        color = white
-        labeljust = r
-    }
-

 Scriptsify
 ----------
 
 Scriptsify
 ----------
 


@@ -213,41 +190,6 @@ work correctly.  Due to the way Git's merge algorithm works, the closer we are
 able to reconstruct a version of the application that was actually used, the
 better off we will be when we try to subsequently upgrade those applications.
 
 able to reconstruct a version of the application that was actually used, the
 better off we will be when we try to subsequently upgrade those applications.
 

-.. todo::
-
-    The following text and graph should be put in a more general overview of
-    the topology of Wizard git repositories.
-
-To give you an idea of what the Git history graph will look like when we
-are done, here is the graph from before, but augmented with the scripts versions:
-
-.. digraph:: master_dag
-
-    rankdir=LR
-    node [shape=square]
-    subgraph cluster_pristine {
-        a -> b -> c
-        a [label="1.0"]
-        b [label="1.1"]
-        c [label="2.0"]
-        label = "pristine"
-        color = white
-        labeljust = r
-    }
-    subgraph cluster_master {
-        as -> bs -> cs
-        as [label="1.0-scripts"]
-        bs [label="1.1-scripts"]
-        cs [label="2.0-scripts"]
-        label = "master"
-        color = white
-        labeljust = r
-    }
-    a -> as
-    b -> bs
-    c -> cs
-    a []
-

 First things first: verify that we are on the master branch::
 
     git checkout master
 First things first: verify that we are on the master branch::
 
     git checkout master

diff --git a/doc/index.rst b/doc/index.rst
index 46d719c9b565f45e74b0e397724019a16ae726db..bddabda88b8335b1aae872d8a12500ec5f657399 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -54,6 +54,7 @@ Table of Contents
 .. toctree::
     :maxdepth: 1
 
 .. toctree::
     :maxdepth: 1
 

+    repo

     create
     upgrade
     testing
     create
     upgrade
     testing

diff --git a/doc/repo.rst b/doc/repo.rst
new file mode 100644 (file)
index 0000000..b4dc876
--- /dev/null
+++ b/doc/repo.rst
@@ -0,0 +1,125 @@
+Anatomy of a repository
+=======================
+
+:Author: Edward Z. Yang <ezyang@mit.edu>
+
+Wizard is all about using Git's excellent directed acyclic graph model of
+history to perform file-system merges as well as keep track of user
+changes on top of ours.  If you are not familiar with the way Git internally
+represents commits, I highly recommend reading
+`Git for Computer Scientists <http://eagain.net/articles/git-for-computer-scientists/>`_
+first.
+
+Wizard takes a simplified view of upstream: from the point of view of the
+pristine branch pointer, history should be a straight-forward progression of
+versions.  Internal development history is discarded, and there is a one-to-one
+mapping of releases and commits.
+
+.. digraph:: pristine_dag
+
+    node [shape=square]
+    subgraph cluster_pristine {
+        c -> b -> a
+        a [label="1.0"]
+        b [label="1.1"]
+        c [label="2.0"]
+        label = "pristine"
+        color = white
+    }
+
+From here, we build "scriptsified" versions of the application, which
+correspond to the master branch.  Every time upstream releases an update,
+we import it into our pristine branch, and then merge the changes into
+master.
+
+.. digraph:: master_dag
+
+    node [shape=square]
+    subgraph cluster_master {
+        cs -> bs -> as
+        as [label="1.0-scripts"]
+        bs [label="1.1-scripts"]
+        cs [label="2.0-scripts"]
+        label = "master"
+        color = white
+    }
+    subgraph cluster_pristine {
+        c -> b -> a
+        a [label="1.0"]
+        b [label="1.1"]
+        c [label="2.0"]
+        label = "pristine"
+        color = white
+    }
+    as -> a
+    bs -> b
+    cs -> c
+
+If there was an error in a deployed scripts version, you might see a structure
+like this:
+
+.. digraph:: scripts2_dag
+
+    node [shape=square]
+    subgraph cluster_master {
+        cs -> bs2 -> bs -> as
+        as [label="1.0-scripts"]
+        bs [label="1.1-scripts",style=dashed]
+        bs2 [label="1.1-scripts2"]
+        cs [label="2.0-scripts"]
+        label = "master"
+        color = white
+    }
+    subgraph cluster_pristine {
+        c -> b -> a
+        a [label="1.0"]
+        b [label="1.1"]
+        c [label="2.0"]
+        label = "pristine"
+        color = white
+    }
+    as -> a
+    bs -> b
+    cs -> c
+
+But such occasions should be rare.  In this particular graph, ``1.1-scripts`` was
+defective, and ``1.1-scripts2`` was the fixed version.
+
+There is another layer to this graph, which is not visible from the repository:
+it contains the user's commits and is unique for each user.
+
+.. digraph:: master_dag
+
+    node [shape=square]
+    subgraph cluster_user {
+        node [shape=ellipse]
+        u -> x -> y -> z
+        u [style=filled,fillcolor=red,fontcolor=white,color=red]
+        label = "master"
+        color = white
+    }
+    subgraph cluster_master {
+        bs -> as
+        as [label="1.0-scripts"]
+        bs [label="1.1-scripts"]
+        color = white
+    }
+    subgraph cluster_pristine {
+        b -> a
+        a [label="1.0"]
+        b [label="1.1"]
+        label = "pristine"
+        color = white
+    }
+    as -> a
+    bs -> b
+    x -> bs
+    z -> as
+
+The red node ``u`` represents uncommitted changes that may exist
+in a user's checkout at any given time.  The untagged commits
+``x``, ``y`` and ``z`` each have a particular story: ``z`` was
+the commit generated when the install took place and the user's
+specific configuration was versioned.  ``y`` was the pre-upgrade
+commit generated so that we could then perform a merge; ``x`` is
+the resulting merge commit.