From 87af364124c7d156064deb258a8f3bcf32705fae Mon Sep 17 00:00:00 2001 From: David Marshall Date: Thu, 12 Apr 2018 17:09:08 -0700 Subject: [PATCH] add examples of prefixed/unprefixed job names --- docs/user-guide/configuration/workflow.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/configuration/workflow.md b/docs/user-guide/configuration/workflow.md index c78d585a..96c7c0d7 100644 --- a/docs/user-guide/configuration/workflow.md +++ b/docs/user-guide/configuration/workflow.md @@ -21,7 +21,7 @@ toc: Workflow is the way that individual jobs are wired together to form a pipeline. This is done by using a `requires` keyword in your job definition with the list of jobs or events that should cause that job to run. Screwdriver defines two events for every pipeline that occur due to SCM events: `~pr`, and `~commit`. These occur when a pull-request is opened, reopened, or modified, and when a commit occurs against the pipeline's branch (respectively). ## Defining Workflow Order -To denote workflow order, use the `requires` keyword under a job with the job names as an array. +To denote workflow order, use the `requires` keyword under a job with the job names as an array. Job names may be prefixed with a tilde to indicate [advanced logic](#advanced-logic). #### Example In the following example, the job, `main`, will start after any SCM pull-request, _or_ commit event. The job, `second`, will run after `main` is successful. @@ -96,7 +96,22 @@ jobs: requires: [~sd@123:first, ~sd@123:second] ``` -The _AND_ and _OR_ logic can be combined in a complex pipeline to allow cases where you want to start a job when `first` _AND_ `second` jobs are successful, _OR_ a `third` job is successful. +### Advanced Logic [Combined] +The _AND_ and _OR_ logic can be combined in a complex pipeline to allow cases where you want to start a job when `first` _AND_ `second` jobs are successful, _OR_ a `third` job is successful as in the following example. + +``` + last: + requires: [first, second , ~sd@123:third] +``` + +If job names are prefixed with tildes in a `requires` line, then the job will start when any of the prefixed jobs is successful _OR_ when all of the unprefixed jobs are successful. For instance, in this contrived example: + +``` + main: + requires: [~sd@123:A, B, ~sd@123:C, D, ~sd@123E, F] +``` + +is equivalent to the Boolean expression `A OR C OR E OR (B AND D AND F)`. Such a complicated `requires` line in an actual workflow should be regarded as a code smell. ## Parallel and Join You can run jobs in parallel by requiring the same job in two or more jobs. To join multiple parallel jobs at a single job you can use the `requires` syntax to require multiple jobs.