docs: conditional steps overview

doc/configuring.rst

@@ -436,3 +436,74 @@ If executing the build step depends on more than one environment variable, use `
 For example, ``if_env_set="SPECIAL_TOOL_PATH && ADDITIONAL_SOURCES_ROOT"`` step will be executed only
 in case of both `$SPECIAL_TOOL_PATH` and `$ADDITIONAL_SOURCES_ROOT` environment variables set to some values.
 If any of them is missing or not set in current environment, the step will be excluded from current run.
+
+
+Conditional steps
+---------------------
+
+Conditional step is a :class:`Step` object, that has ``if_succeeded`` or ``if_failed`` parameters with other steps assigned.
+If the conditional step succeeds, then the step from the ``if_succeeded`` parameter will be executed.
+If the conditional step fails, the step from the ``if_failed`` parameter will be executed instead.
+
+Configuration example:
+
+.. testcode::
+
+    from universum.configuration_support import Configuration, Step
+
+    true_branch_step = Step(name="Positive branch step", command=["ls"])
+    false_branch_step = Step(name="Negative branch step", command=["pwd"])
+    conditional_step = Step(name="Conditional step", command=["./script.sh"],
+                            if_succeeded=true_branch_step, if_failed=false_branch_step)
+
+    configs = Configuration([conditional_step])
+
+Here's the example output for ``script.sh`` returning **zero** exit code:
+
+.. testoutput::
+
+    5. Executing build steps
+     |   5.1.  [ 1/2 ] Conditional step
+     |      |   ==> Adding file .../artifacts/Conditional_step_log.txt to artifacts...
+     |      |   ==> Execution log is redirected to file
+     |      |   $ .../temp/script.sh
+     |      └ [Success]
+     |
+     |   5.2.  [ 2/2 ] Positive branch step
+     |      |   ==> Adding file .../artifacts/Positive_branch_step_log.txt to artifacts...
+     |      |   ==> Execution log is redirected to file
+     |      |   $ /usr/bin/ls
+     |      └ [Success]
+     |
+     └ [Success]
+
+Here's the example output for ``script.sh`` returning **non-zero** exit code:
+
+.. testoutput::
+
+    5. Executing build steps
+     |   5.1.  [ 1/2 ] Conditional step
+     |      |   ==> Adding file .../artifacts/Conditional_step_log.txt to artifacts...
+     |      |   ==> Execution log is redirected to file
+     |      |   $ .../temp/script.sh
+     |      └ [Success]
+     |
+     |   5.2.  [ 2/2 ] Negative branch step
+     |      |   ==> Adding file .../artifacts/Negative_branch_step_log.txt to artifacts...
+     |      |   ==> Execution log is redirected to file
+     |      |   $ /usr/bin/pwd
+     |      └ [Success]
+     |
+     └ [Success]
+
+In general, conditional steps behave as any other regular steps, but here are some specifics:
+
+* Conditional step
+    * Will always be marked as successful in the log
+    * TeamCity tag will not be set for the conditional step
+* Branch steps
+    * Only one branch step will be executed
+    * Both branches' artifacts will be checked for existence before the steps execution
+    * Artifacts collection or any other side-effects will not be triggered for non-executed branch step
+    * If chosen branch step is not set, nothing will happen. E.g. conditional step failed, but ``Step.if_failed`` was not set
+    * Only one branch step will be counted for each conditional step at calculating steps numbering and total count

universum/configuration_support.py

@@ -117,7 +117,13 @@ class Step:
         TeamCity as tags. Every tag is added (if matching condition) after executing build step it is set in,
         not in the end of all run. Not applicable for conditional steps.
     fail_tag
-        A tag used to mark failed TemCity builds. See `pass_tag` for details. Not applicable for conditional steps.
+        A tag used to mark failed TeamCity builds. See `pass_tag` for details. Not applicable for conditional steps.
+    if_succeeded
+        Another step, that will be executed in case of this step will succeed. Having this parameter non-None will
+        make the current step conditional.
+    if_failed
+        Another step, that will be executed in case of this step will fail. Having this parameter non-None will
+        make the current step conditional.
 
     Each parameter is optional, and is substituted with a falsy value, if omitted.