From 582186dd38269c452bfe1558e588cb74e76ae97b Mon Sep 17 00:00:00 2001 From: miltolstoy Date: Tue, 29 Nov 2022 07:20:17 +0200 Subject: [PATCH 1/5] docs: conditional steps overview --- doc/configuring.rst | 65 ++++++++++++++++++++++++++++++ universum/configuration_support.py | 8 +++- 2 files changed, 72 insertions(+), 1 deletion(-) diff --git a/doc/configuring.rst b/doc/configuring.rst index 2f610777..756be95a 100644 --- a/doc/configuring.rst +++ b/doc/configuring.rst @@ -436,3 +436,68 @@ 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 - :class:`Step`, that has ``if_succeeded`` and/or ``if_failed`` parameters with other steps assigned. +If the conditional step will succeed, then the step from the ``if_succeeded`` parameter will be executed. +If the conditional step will fail, 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]) + +If ``script.sh`` will return 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] + +If ``script.sh`` will return 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] + +Mainly, conditional steps behave as other regular steps, but there are some specifics: + +* Conditional step will be always marked as succeeded in log +* Only one branch step will be executed (``if_succeeded`` or ``if_failed``), so artifacts collection or any other + side-effects will not be triggered for non-executed branch step diff --git a/universum/configuration_support.py b/universum/configuration_support.py index 9c5e4ac6..91bbaf93 100644 --- a/universum/configuration_support.py +++ b/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. From aa6da13d3d8bdc0de3e7f3f2c10582c31165cc40 Mon Sep 17 00:00:00 2001 From: miltolstoy Date: Fri, 2 Dec 2022 07:14:27 +0200 Subject: [PATCH 2/5] review comments fixes --- doc/configuring.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/configuring.rst b/doc/configuring.rst index 756be95a..61593229 100644 --- a/doc/configuring.rst +++ b/doc/configuring.rst @@ -441,9 +441,9 @@ If any of them is missing or not set in current environment, the step will be ex Conditional steps --------------------- -Conditional step - :class:`Step`, that has ``if_succeeded`` and/or ``if_failed`` parameters with other steps assigned. -If the conditional step will succeed, then the step from the ``if_succeeded`` parameter will be executed. -If the conditional step will fail, the step from the ``if_failed`` parameter will be executed instead. +Conditional step is a :class:`Step` object, that has ``if_succeeded`` and/or ``if_failed`` parameters with other steps assigned. +If the conditional step succeed, then the step from the ``if_succeeded`` parameter will be executed. +If the conditional step fail, the step from the ``if_failed`` parameter will be executed instead. Configuration example: @@ -458,7 +458,7 @@ Configuration example: configs = Configuration([conditional_step]) -If ``script.sh`` will return zero exit code: +Here's the example output for ``script.sh`` returning **zero** exit code: .. testoutput:: @@ -477,7 +477,7 @@ If ``script.sh`` will return zero exit code: | └ [Success] -If ``script.sh`` will return non-zero exit code: +Here's the example output for ``script.sh`` returning **non-zero** exit code: .. testoutput:: @@ -496,8 +496,11 @@ If ``script.sh`` will return non-zero exit code: | └ [Success] -Mainly, conditional steps behave as other regular steps, but there are some specifics: +In general, conditional steps behave as any other regular steps, but here are some specifics: -* Conditional step will be always marked as succeeded in log +* Conditional step will always be marked as successful in log * Only one branch step will be executed (``if_succeeded`` or ``if_failed``), so artifacts collection or any other side-effects will not be triggered for non-executed branch step +* Both branches artifacts will be checked for existense before steps execution +* TeamCity tag will not be set for the conditional step +* Only one branch step will counted for each conditional step at calculating steps numbering and total count From ed33cd1d63690e4db9268b974ff919ea071e8374 Mon Sep 17 00:00:00 2001 From: miltolstoy Date: Fri, 2 Dec 2022 07:21:09 +0200 Subject: [PATCH 3/5] reorganize 'specifics' section --- doc/configuring.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/configuring.rst b/doc/configuring.rst index 61593229..bf0b480b 100644 --- a/doc/configuring.rst +++ b/doc/configuring.rst @@ -498,9 +498,12 @@ Here's the example output for ``script.sh`` returning **non-zero** exit code: In general, conditional steps behave as any other regular steps, but here are some specifics: -* Conditional step will always be marked as successful in log -* Only one branch step will be executed (``if_succeeded`` or ``if_failed``), so artifacts collection or any other - side-effects will not be triggered for non-executed branch step -* Both branches artifacts will be checked for existense before steps execution -* TeamCity tag will not be set for the conditional step -* Only one branch step will counted for each conditional step at calculating steps numbering and total count +* 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 From 62b515712ce40576a0dcb89108ea9697e08abdfe Mon Sep 17 00:00:00 2001 From: miltolstoy Date: Thu, 8 Dec 2022 14:57:09 +0200 Subject: [PATCH 4/5] review comments fixes --- doc/configuring.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/configuring.rst b/doc/configuring.rst index bf0b480b..475f12f0 100644 --- a/doc/configuring.rst +++ b/doc/configuring.rst @@ -441,9 +441,9 @@ If any of them is missing or not set in current environment, the step will be ex Conditional steps --------------------- -Conditional step is a :class:`Step` object, that has ``if_succeeded`` and/or ``if_failed`` parameters with other steps assigned. -If the conditional step succeed, then the step from the ``if_succeeded`` parameter will be executed. -If the conditional step fail, the step from the ``if_failed`` parameter will be executed instead. +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: @@ -505,5 +505,5 @@ In general, conditional steps behave as any other regular steps, but here are so * 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) + * 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 From f7540c2a1ead20a870fc90b2f25b42906f6aa004 Mon Sep 17 00:00:00 2001 From: miltolstoy Date: Sat, 10 Dec 2022 07:32:30 +0200 Subject: [PATCH 5/5] fix review comment --- doc/configuring.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/configuring.rst b/doc/configuring.rst index 475f12f0..05ec6ffe 100644 --- a/doc/configuring.rst +++ b/doc/configuring.rst @@ -505,5 +505,6 @@ In general, conditional steps behave as any other regular steps, but here are so * 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 + * If chosen branch step is not set, nothing will happen. + For example, if the the ``Step.if_failed`` is not set and conditional step fails during the execution, nothing will happen. * Only one branch step will be counted for each conditional step at calculating steps numbering and total count