Merge pull request #126 from abayer/parallel-stages-rfc

RFC: JENKINS-41334: Parallel stage execution
jenkinsci · Mar 21, 2017 · c033644c282e0f1727fdb0b6beddaff6a5819723 · c033644
2 parents 00dc233 + 74852f2
commit c033644c282e0f1727fdb0b6beddaff6a5819723
Unified Split

Showing with 76 additions and 0 deletions.

+76 −0 rfc/JENKINS-41334-parallel-stage-execution.md
diff --git a/rfc/JENKINS-41334-parallel-stage-execution.md b/rfc/JENKINS-41334-parallel-stage-execution.md
@@ -0,0 +1,76 @@
+  
+## RFC: [JENKINS-41334](https://issues.jenkins-ci.org/browse/JENKINS-41334) - Parallel stage execution
+  
+
+  
+* Author: Andrew Bayer
+  
+* Created Date: February 27, 2017
+  
+* Approved Date: March 21, 2017
+  
+* Target Release: 1.3
+  
+* JIRA: [JENKINS-41334](https://issues.jenkins-ci.org/browse/JENKINS-41334)
+  
+* Status: Aprpoved
+  
+
+  
+### Problem Statement
+  
+
+  
+The `parallel` step does not fit smoothly into Declarative. It doesn't
+  
+allow for parallel stage execution, it doesn't utilize the `agent`
+  
+definition, etc. There needs to be the ability to run `stage`s in
+  
+parallel, with the full power of the Declarative syntax enabled -
+  
+i.e., `agent`, `post`, `when`, etc.
+  
+
+  
+### Syntax
+  
+
+  
+#### Proposed example
+  
+
+  
+```groovy
+  
+stage('foo') {
+  
+    parallel {
+  
+        stage('first') {
+  
+            steps {
+  
+                echo "First branch"
+  
+            }
+  
+        }
+  
+        stage('second') {
+  
+            steps {
+  
+                echo "Second branch"
+  
+            }
+  
+        }
+  
+    }
+  
+}
+  
+```
+  
+
+  
+#### Details
+  
+
+  
+* A `stage` has to contain one and only one of `steps` or
+  
+    `parallel`. They cannot be combined in the same `stage`.
+  
+* `stage` configuration can be done on both a `stage` containing
+  
+    `parallel`, or `stage`s within `parallel`, i.e., `agent`, `when`,
+  
+    `post`, etc.
+  
+* `agent`, `environment`, and `tools` specified on the "parent"
+  
+    `stage` will apply to child `stage`s in the same way that top-level
+  
+    configuration applies to `stage`s currently.
+  
+* Arbitrarily deep nesting of parallel `stage`s would not be
+  
+    allowed. Only `stage`s that themselves are not within a `parallel`
+  
+    would be able to contain further `parallel` `stage`s.
+  
+* `stage`s within a `parallel` would not allow use of the `parallel`
+  
+    step either, so as to prevent visualization confusion.
+  
+* Naming of `parallel` is up for debate.
+  
+
+  
+### Runtime Implementation
+  
+
+  
+Based on input from the Blue Ocean team regarding the two possible runtime
+  
+implementations (actually nesting stages within the `parallel` branches vs 
+  
+simply utilizing the `parallel` branches), we have decided to just use the
+  
+`parallel` branches themselves. This should hopefully require little to no
+  
+changes in Blue Ocean visualization or Bismuth in order to work, meaning only
+  
+changes to the editor will be needed outside of Declarative itself.
+  
+
+  
+Each `parallel` branch will be given the `stage` name specified, with `agent`,
+  
+`environment`, etc configured before running the `steps` for the `stage` inside
+  
+the `parallel` branch, followed by any `post` actions. This will require some
+  
+changes in Declarative's runtime logic to properly attach the supplementary 
+  
+metadata we attach to `stage`s (i.e., "Failed but continued", "Skipped due to
+  
+earlier failure", etc) to branches, but that won't be difficult. Everything 
+  
+else will just function properly right out of the box.
+  
+
+  
+### Visualization
+  
+
+  
+No changes should be needed in Blue Ocean visualization, since we will simply
+  
+be using `parallel` branches with no nested `StageStep` executions.