Merge "Doc: enhance gating reference with diagrams"
This commit is contained in:
commit
1f8d1760b2
|
@ -25,7 +25,7 @@ sys.path.insert(0, os.path.abspath('../..'))
|
||||||
|
|
||||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = []
|
extensions = [ 'sphinxcontrib.blockdiag' ]
|
||||||
#extensions = ['sphinx.ext.intersphinx']
|
#extensions = ['sphinx.ext.intersphinx']
|
||||||
#intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
|
#intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
|
||||||
|
|
||||||
|
|
|
@ -58,9 +58,15 @@ succession::
|
||||||
A, B, C, D, E
|
A, B, C, D, E
|
||||||
|
|
||||||
Zuul queues those changes in the order they were approved, and notes
|
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.
|
Zuul then starts immediately testing all of the changes in parallel.
|
||||||
But in the case of changes that depend on others, it instructs the
|
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 D: merge changes A, B, C and D, then test
|
||||||
Jobs for E: merge changes A, B, C, D and E, 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
|
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
|
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
|
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;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
|
@ -2,6 +2,7 @@ hacking>=0.5.6,<0.8
|
||||||
|
|
||||||
coverage>=3.6
|
coverage>=3.6
|
||||||
sphinx>=1.1.2
|
sphinx>=1.1.2
|
||||||
|
sphinxcontrib-blockdiag>=0.5.5
|
||||||
docutils==0.9.1
|
docutils==0.9.1
|
||||||
discover
|
discover
|
||||||
fixtures>=0.3.14
|
fixtures>=0.3.14
|
||||||
|
|
Loading…
Reference in New Issue