From 7b206e87803285805a97267d72359b8d57f8b7f8 Mon Sep 17 00:00:00 2001
From: Dibyo Mukherjee <dibyo@google.com>
Date: Mon, 29 Jul 2019 11:50:20 -0400
Subject: [PATCH] Add intial skeleton docs for conditions

Signed-off-by: Dibyo Mukherjee <dibyo@google.com>
---
 docs/conditions.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/pipelines.md  | 24 +++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 docs/conditions.md

diff --git a/docs/conditions.md b/docs/conditions.md
new file mode 100644
index 00000000000..8a1dac9c7a6
--- /dev/null
+++ b/docs/conditions.md
@@ -0,0 +1,52 @@
+# Conditions
+
+This document defines `Conditions` and their capabilities.
+
+*NOTE*: This feature is currently a WIP.
+
+---
+
+- [Syntax](#syntax)
+  - [Check](#check)
+  - [Parameters](#parameters)
+
+- [Examples](#examples)
+
+## Syntax
+
+To define a configuration file for a `Condition` resource, you can specify the
+following fields:
+
+- Required:
+  - [`apiVersion`][kubernetes-overview] - Specifies the API version, for example
+    `tekton.dev/v1alpha1`.
+  - [`kind`][kubernetes-overview] - Specify the `Condition` resource object.
+  - [`metadata`][kubernetes-overview] - Specifies data to uniquely identify the
+    `Condition` resource object, for example a `name`.
+  - [`spec`][kubernetes-overview] - Specifies the configuration information for
+    your `Condition` resource object. In order for a `Condition` to do anything,
+    the spec must include:
+    - [`check`](#check) - Specifies a container that you want to run for evaluating the condition 
+
+[kubernetes-overview]:
+  https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+
+### Check
+
+The `check` field is required. You define a single check to define the body of a `Condition`. The 
+check must specify a container image that adheres to the container contract. The container image 
+runs till completion. The container must exit successfully i.e. with an exit code 0 for the 
+condition evaluation to be successful. All other exit codes are considered to be a condition check
+failure.
+
+## Examples
+
+For complete examples, see
+[the examples folder](https://github.com/tektoncd/pipeline/tree/master/examples).
+
+---
+
+Except as otherwise noted, the content of this page is licensed under the
+[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/),
+and code samples are licensed under the
+[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
\ No newline at end of file
diff --git a/docs/pipelines.md b/docs/pipelines.md
index a47d6aabf9d..caf86f37795 100644
--- a/docs/pipelines.md
+++ b/docs/pipelines.md
@@ -45,6 +45,8 @@ following fields:
       - [`retries`](#retries) - Used when the task is wanted to be executed if
         it fails. Could a network error or a missing dependency. It does not
         apply to cancellations.
+      - [`conditions`](#conditions) - Used when a task is to be executed only if the specified
+        conditons are evaluated to be true.
 
 [kubernetes-overview]:
   https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
@@ -285,6 +287,28 @@ In this example, the task "build-the-image" will be executed and if the first
 run fails a second one would triggered. But, if that fails no more would
 triggered: a max of two executions.
 
+
+#### 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) 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 in the pipeline are still run.
+
+```yaml
+tasks:
+  - name: conditional-task
+    taskRef:
+      name: build-push
+    conditions:
+      - conditionRef: my-condition
+```
+
+In this example, `my-condition` refers to a [Condition](#conditions) custom resource. The `build-push` 
+task will only be executed if the condition evaluates to true. 
+
 ## Ordering
 
 The [Pipeline Tasks](#pipeline-tasks) in a `Pipeline` can be connected and run