From 3a43e14bda52ce187d8fbb6371aa64dada6e3923 Mon Sep 17 00:00:00 2001
From: Antoine Musso <hashar@free.fr>
Date: Wed, 30 Oct 2013 23:51:58 +0100
Subject: [PATCH] Doc: enhance gating reference with diagrams

ASCII art is fun but not savvy for project managers and directors. This
patch slightly enhance the 'gating' documentation with colored diagrams.

This is made possible via http://blockdiag.com/ by Takeshi KOMIYA who
even took the time to write a sphinx extension.  The version dependency
is at the very least 0.5.5, but might be higher :/

Change-Id: Ibe3c2674a5dff2114c40a84ffdec8a8886b1b21b
---
 doc/source/conf.py    |   2 +-
 doc/source/gating.rst | 136 ++++++++++++++++++++++++++++++++++++++----
 test-requirements.txt |   1 +
 3 files changed, 127 insertions(+), 12 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index d7142ad4a9..422f03c571 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -25,7 +25,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [ 'sphinxcontrib.blockdiag' ]
 #extensions = ['sphinx.ext.intersphinx']
 #intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
 
diff --git a/doc/source/gating.rst b/doc/source/gating.rst
index cf5964c0df..f3f2d3c960 100644
--- a/doc/source/gating.rst
+++ b/doc/source/gating.rst
@@ -58,9 +58,15 @@ succession::
   A, B, C, D, E
 
 Zuul queues those changes in the order they were approved, and notes
-that each subsequent change depends on the one ahead of it merging::
+that each subsequent change depends on the one ahead of it merging:
 
-  A <-- B <-- C <-- D <-- E
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+    A <- B <- C <- D <- E;
+  }
 
 Zuul then starts immediately testing all of the changes in parallel.
 But in the case of changes that depend on others, it instructs the
@@ -74,23 +80,131 @@ well::
   Jobs for D: merge changes A, B, C and D, then test
   Jobs for E: merge changes A, B, C, D and E, then test
 
-If changes *A* and *B* pass tests, and *C*, *D*, and *E* fail::
+Hence jobs triggered to tests A will only test A and ignore B, C, D:
 
-  A[pass] <-- B[pass] <-- C[fail] <-- D[fail] <-- E[fail]
+.. blockdiag::
 
-Zuul will merge change *A* followed by change *B*, leaving this queue::
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+    master -> A -> B -> C -> D -> E;
+    group jobs_for_A {
+        label = "Merged changes for A";
+        master -> A;
+    }
+    group ignored_to_test_A {
+        label = "Ignored changes";
+        color = "lightgray";
+        B -> C -> D -> E;
+    }
+  }
 
-  C[fail] <-- D[fail] <-- E[fail]
+The jobs for E would include the whole dependency chain: A, B, C, D, and E.
+E will be tested assuming A, B, C, and D passed:
+
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+    group jobs_for_E {
+        label = "Merged changes for E";
+        master -> A -> B -> C -> D -> E;
+    }
+  }
+
+If changes *A* and *B* pass tests (green), and *C*, *D*, and *E* fail (red):
+
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+
+    A [color = lightgreen];
+    B [color = lightgreen];
+    C [color = pink];
+    D [color = pink];
+    E [color = pink];
+
+    master <- A <- B <- C <- D <- E;
+  }
+
+Zuul will merge change *A* followed by change *B*, leaving this queue:
+
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+
+    C [color = pink];
+    D [color = pink];
+    E [color = pink];
+
+    C <- D <- E;
+  }
 
 Since *D* was dependent on *C*, it is not clear whether *D*'s failure is the
-result of a defect in *D* or *C*::
+result of a defect in *D* or *C*:
 
-  C[fail] <-- D[unknown] <-- E[unknown]
+.. blockdiag::
 
-Since *C* failed, it will report the failure and drop *C* from the queue::
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
 
-  D[unknown] <-- E[unknown]
+    C [color = pink];
+    D [label = "D\n?"];
+    E [label = "E\n?"];
+
+    C <- D <- E;
+  }
+
+Since *C* failed, Zuul will report its failure and drop *C* from the queue,
+keeping D and E:
+
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+
+    D [label = "D\n?"];
+    E [label = "E\n?"];
+
+    D <- E;
+  }
 
 This queue is the same as if two new changes had just arrived, so Zuul
 starts the process again testing *D* against the tip of the branch, and
-*E* against *D*.
+*E* against *D*:
+
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+    master -> D -> E;
+    group jobs_for_D {
+        label = "Merged changes for D";
+        master -> D;
+    }
+    group ignored_to_test_D {
+        label = "Skip";
+        color = "lightgray";
+        E;
+    }
+  }
+
+.. blockdiag::
+
+  blockdiag foo {
+    node_width = 40;
+    span_width = 40;
+    group jobs_for_E {
+        label = "Merged changes for E";
+        master -> D -> E;
+    }
+  }
+
diff --git a/test-requirements.txt b/test-requirements.txt
index b220203ee9..90d4934a3e 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -2,6 +2,7 @@ hacking>=0.5.6,<0.8
 
 coverage>=3.6
 sphinx>=1.1.2
+sphinxcontrib-blockdiag>=0.5.5
 docutils==0.9.1
 discover
 fixtures>=0.3.14