Add new doc for conditional workflows, link to it in the api changes,…

… and add a note on the design doc to read the new doc for final design (#33)

designs-for-feedback/trigger-workflows-in-pipeline.md

@@ -1,4 +1,12 @@
-# Request for Comment: Trigger an individual workflow
+
+# NOTE: THIS DESIGN DOCUMENT IS NOW OBSOLETE.
+PLEASE SEE [THE DOC ON CONDITIONAL WORKFLOWS](../docs/conditional-workflows.md) FOR INFO ON THE ACCEPTED IMPLEMENTATION.
+
+
+
+
+
+
 ## Problem statement
 Users want to be able to trigger a pipeline, selecting a specific workflow in
 the configuration to run. They also need a way for such manually triggered
@@ -46,7 +54,7 @@ workflows:
           condition: << pipeline.parameters.deploy >>
           steps:
             - deploy
-            
+
 jobs:
   ...
 ```

docs/api-changes.md

@@ -37,7 +37,7 @@ Retrieve an individual project by its unique slug.
 ### POST /project/:project_slug/pipeline
 Trigger a new pipeline run on a project.
 
-To trigger with parameters you pass a `parameters` map inside a JSON object as part of the POST body. For details on passing pipeline parameters when triggering pipelines with the API see the [pipeline parameters documentation](pipeline-parameters.md).
+To trigger with parameters you pass a `parameters` map inside a JSON object as part of the POST body. For details on passing pipeline parameters when triggering pipelines with the API see the [pipeline parameters documentation](pipeline-parameters.md). Note that pipeline parameters can also be used to populate a `when` or `unless` clause on a workflow to conditionally run one or more workflows. See the [conditional workflows](conditional-workflows.md) doc for more information.
 
 ### GET /pipeline/:id
 Retrieve a particular pipeline by its unique ID. This will return basic information about the pipeline, including triggering information and the IDs of running workflows associated with the pipeline. Please note that workflows are created asyncronously to the creation of a pipeline, so in automated scripts if you trigger a pipeline it may not immediately have knowledge of all workflows that will be run as a result of your trigger. You may need to make subsequent, delayed requests to get all workflow IDs. In most cases this should be a matter of a few seconds, but in some situations the queues between our pipeline ingestion machinery and our workflows conductor can take longer to proceed.

docs/conditional-workflows.md

@@ -0,0 +1,48 @@
+# Conditional Workflows
+New as of June 2019, you can use a `when` clause (and coming soon, also support for the inverse clause `unless`) under a workflow declaration with a boolean value to decide whether or not to run that workflow.
+
+The most common use of this construct is to use a [pipeline parameter](pipeline-parameters.md) as the value, allowing an API trigger to pass that parameter to determine which workflows to run.
+
+Below is an example configuration using two different pipeline parameters, one used to drive whether a particular workflow will run and another to determine if a particular step will run.
+
+```yaml
+version: 2.1
+
+parameters:
+  run_integration_tests:
+    type: boolean
+    default: false
+  deploy:
+    type: boolean
+    default: false
+
+workflows:
+  version: 2
+  integration_tests:
+    when: << pipeline.parameters.run_integration_tests >>
+    jobs:
+      - mytestjob
+      - when:
+          condition: << pipeline.parameters.deploy >>
+          steps:
+            - deploy
+
+jobs:
+  ...
+```
+
+The above would prevent the workflow `integration_tests` from being triggered
+unless it was invoked explicitly when the pipeline is triggered with the following in the POST body:
+
+```json
+{
+    "parameters": {
+        "run_integration_tests": true
+    }
+}
+```
+
+The `when` key actually accepts any boolean, not just pipeline parameters,
+though pipeline parameters will be the primary use of this feature until we implement others.
+
+Coming soon: `when` also comes with an alternative of `unless`, which inverts truthiness of the condition.