From 29a0671bddfb7a20e962719634ee20cec97d3bed Mon Sep 17 00:00:00 2001
From: Jonas Pettersson <jlpettersson@gmail.com>
Date: Sun, 17 May 2020 14:35:18 +0200
Subject: [PATCH] Improve documentation about guarding Task execution using
 Conditions

As noted in #2635, it is not very clear what a Condition is in the context of a Pipeline.
And it is not clear how they work or what happens after.

This commit use the concept with "Guards" to explain how to guard Task execution within a Pipeline
using Condition resources. An example showing the flow when a Condition is not successfully evaluated
is also added.

/kind documentation
---
 docs/pipelines.md | 48 +++++++++++++++++++++++++++++------------------
 1 file changed, 30 insertions(+), 18 deletions(-)

diff --git a/docs/pipelines.md b/docs/pipelines.md
index e8cf1dbadf8..9ef247f830f 100644
--- a/docs/pipelines.md
+++ b/docs/pipelines.md
@@ -15,7 +15,7 @@ weight: 3
     - [Using the `from` parameter](#using-the-from-parameter)
     - [Using the `runAfter` parameter](#using-the-runafter-parameter)
     - [Using the `retries` parameter](#using-the-retries-parameter)
-    - [Specifying execution `Conditions`](#specifying-execution-conditions)
+    - [Guard `Task` execution using `Conditions`](#guard-task-execution-using-conditions)
     - [Configuring the failure timeout](#configuring-the-failure-timeout)
     - [Configuring execution results at the `Task` level](#configuring-execution-results-at-the-task-level)
   - [Configuring execution results at the `Pipeline` level](#configuring-execution-results-at-the-pipeline-level)
@@ -312,32 +312,44 @@ tasks:
       name: build-push
 ```
 
-### Specifying execution `Conditions`
+### Guard `Task` execution using `Conditions`
 
-Sometimes you will need to run tasks only when some conditions are true. The `conditions` field
-allows you to list a series of references to [`Conditions`](./conditions.md) that are run before the task
-is run. If all of the conditions evaluate to true, the task is run. If any of the conditions are false,
-the Task is not run. Its status.ConditionSucceeded is set to False with the reason set to  `ConditionCheckFailed`.
-However, unlike regular task failures, condition failures do not automatically fail the entire pipeline
-run -- other tasks that are not dependent on the task (via `from` or `runAfter`) are still run.
+To run a `Task` only when certain conditions are met, it is possible to _guard_ task execution using
+the `conditions` field. The `conditions` field allows you to list a series of references to
+[`Condition`](./conditions.md) resources. The declared `Conditions` are run before the `Task` is run.
+If all of the conditions successfully evaluate, the `Task` is run. If any of the conditions fails,
+the `Task` is not run and the `TaskRun` status field `ConditionSucceeded` is set to `False` with the
+reason set to `ConditionCheckFailed`.
+
+In this example, `is-master-branch` refers to a [Condition](conditions.md) resource. The `deploy`
+task will only be executed if the condition successfully evaluates.
 
 ```yaml
 tasks:
-  - name: conditional-task
-    taskRef:
-      name: build-push
+  - name: deploy-if-branch-is-master
     conditions:
-      - conditionRef: my-condition
+      - conditionRef: is-master-branch
         params:
-          - name: my-param
+          - name: branch-name
             value: my-value
-        resources:
-          - name: workspace
-            resource: source-repo
+    taskRef:
+      name: deploy
 ```
 
-In this example, `my-condition` refers to a [Condition](conditions.md) custom resource. The `build-push`
-task will only be executed if the condition evaluates to true.
+Unlike regular task failures, condition failures do not automatically fail the entire `PipelineRun` -- 
+other tasks that are **not dependent** on the `Task` (via `from` or `runAfter`) are still run.
+
+In this example, `(task C)` has a `condition` set to _guard_ its execution. If the condition
+is **not** successfully evaluated, task `(task D)` will not be run, but all other tasks in the pipeline
+that not depend on `(task C)` will be executed and the `PipelineRun` will successfully complete.
+ 
+  ```
+         (task B) — (task E)
+       / 
+   (task A) 
+       \
+         (guarded task C) — (task D)
+  ```
 
 Resources in conditions can also use the [`from`](#using-the-from-parameter) field to indicate that they
 expect the output of a previous task as input. As with regular Pipeline Tasks, using `from`