# HG changeset patch
# User Norm Jacobs <Norm.Jacobs@Sun.COM>
# Date 1288922790 18000
# Node ID 50cc241a2b9a5eadb9c933a8bee08147da15e07b
# Parent  84267c1130e9dd7ebe5ea3d90195979762213875
add basic overview of incoming/gate/mirror operation

diff -r 84267c1130e9 -r 50cc241a2b9a doc/gate-mechanics.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/gate-mechanics.txt	Thu Nov 04 21:06:30 2010 -0500
@@ -0,0 +1,93 @@
+
+                Userland Gate Mechanics
+
+The userland consolidation operates a set of Mercurial repositories that work
+together to manage the tools, source code, and build recipies.  These
+repositories are the integration repository, gate, and external mirror.  This is
+similiar to how the Solaris ON, SFW, and other gates operates, however there
+are a few subtle differences.  In ON and other consolidations, the integration
+repository is that gate and contains the canonical source.  Once a changeset
+is committed, it becomes a part of the canonical source.  In the case of ON,
+the changeset is immediately pushed to the clone repository.  SFW and other
+consolidations push changes from their canonical gate to a clone repository
+nightly.  In the userland consolidation, developers will commit changes to the
+integration gate.  These changes will not be accepted until some basic
+validation is performed.  Once the validation completes successfully, the
+changes are accepted and pushed into the canonical source gate.
+
+Integration repository (ssh://ulhg@userland//nevada/incoming)
+	The integration gate is the Mercurial repository that all tools, source
+    code, and build recipies are committed to.  Unlike ON, SFW, and other
+    Solaris gates this source code repository does not contains the canonical
+    source for the product.  This repository is a staging area for change
+    integration and acceptance.
+
+	    hg push to integration gate
+	        |
+	        v
+	    lock gate
+	        |
+	        v
+	    validate changeset(s) -> failed --> rollback changeset(s) 
+	        |                                   |
+	        v                                   |
+	    accepted                                |
+	        |                                   |
+	        v                                   v
+	    push to clone -------------------> unlock gate
+	                                            |
+	                                            v
+	                                       update bug db
+	                                            |
+	                                            v
+	                                       notify committer
+
+    So, the basic flow works something like this:  A user pushes a changeset
+    to the integration gate.  Mercurial locks the gate to block any other
+    attempts to operate on the gate while it is validating the changeset.
+    At this point, validation is started in the background, a message is
+    displayed, and control is returned to the user.  Validation continues
+    in the background.  If validation completes successfully, the changeset(s)
+    are pushed to the clone, the gate is unlocked, the bug database is updated,
+    and the user is notified of the changeset acceptance.  If the validation
+    fails, the changeset(s) are rolled back, the gate is unlocked, and the
+    user is notified of the failure.
+
+    Changeset validation will include the following:
+        multi-delta update check
+        commit comment validation
+        bugdb validation
+      future operations
+        source archive download
+        incremental build on all architectures
+        unit test on all architectures
+        package publication for all architectures
+
+
+Canonical source repository (ssh://anon@userland//nevada/gate)
+    The clone gate is actually the mercurial repository that contains the
+    canonical tools, source code, and build recipies for the product.  It
+    should always be in a stable, buildable state.  When changes are pushed
+    to this gate, they are mirrored on the external mirror repository from
+    here.
+
+        clone update
+            |
+            v
+        push to external mirror
+            |
+            v
+        notify gatelings
+
+
+External mirror repository (ssh://anon@hg.opensolaris.org//hg/userland/gate)
+    The external mirror is the mercurial repository that contains an externally
+    accessible copy of the canonical tools, source code, and build recipies for
+    the product.  It should always be in a stable, buildable state.
+
+        external mirror update
+            |
+            v
+        notify gatelings
+
+# vi:set fdm=marker expandtab ts=4: