Browse Source

Merge "Doc: enhance gating reference with diagrams"

changes/75/58075/1
Jenkins 9 years ago committed by Gerrit Code Review
parent
commit
1f8d1760b2
  1. 2
      doc/source/conf.py
  2. 136
      doc/source/gating.rst
  3. 1
      test-requirements.txt

2
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)}

136
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:
.. blockdiag::
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;
}
}
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];
A[pass] <-- B[pass] <-- C[fail] <-- D[fail] <-- E[fail]
master <- A <- B <- C <- D <- E;
}
Zuul will merge change *A* followed by change *B*, leaving this queue::
Zuul will merge change *A* followed by change *B*, leaving this queue:
C[fail] <-- D[fail] <-- E[fail]
.. 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*:
.. blockdiag::
blockdiag foo {
node_width = 40;
span_width = 40;
C[fail] <-- D[unknown] <-- E[unknown]
C [color = pink];
D [label = "D\n?"];
E [label = "E\n?"];
Since *C* failed, it will report the failure and drop *C* from the queue::
C <- D <- E;
}
D[unknown] <-- E[unknown]
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;
}
}

1
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

Loading…
Cancel
Save