From: Edward Z. Yang Date: Wed, 25 Nov 2009 06:14:46 +0000 (-0500) Subject: Add anatomy of a repository docs. X-Git-Url: https://scripts.mit.edu/gitweb/wizard.git/commitdiff_plain/afc5885671e371c8dacb423136be38f5dd696b72 Add anatomy of a repository docs. Signed-off-by: Edward Z. Yang --- diff --git a/doc/create.rst b/doc/create.rst index 352cc63..c040f55 100644 --- a/doc/create.rst +++ b/doc/create.rst @@ -180,29 +180,6 @@ can also create a pristine branch:: 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 ---------- @@ -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. -.. 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 diff --git a/doc/index.rst b/doc/index.rst index 46d719c..bddabda 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -54,6 +54,7 @@ Table of Contents .. toctree:: :maxdepth: 1 + repo create upgrade testing diff --git a/doc/repo.rst b/doc/repo.rst new file mode 100644 index 0000000..b4dc876 --- /dev/null +++ b/doc/repo.rst @@ -0,0 +1,125 @@ +Anatomy of a repository +======================= + +:Author: Edward Z. Yang + +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 `_ +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.