Rename Choice to Parallel and cases to branches (#1786)

Author: lionelvillard

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 .idea/
 .vscode/
+.history/

docs/eventing/choice.md

@@ -0,0 +1,45 @@
+---
+title: "Parallel"
+weight: 20
+type: "docs"
+---
+
+Parallel CRD provides a way to easily define a list of branches, each receiving
+the same CloudEvent sent to the Parallel ingress channel. Typically, each branch
+consists of a filter function guarding the execution of the branch.
+
+Parallel creates `Channel`s and `Subscription`s under the hood.
+
+## Usage
+
+### Parallel Spec
+
+Parallel has three parts for the Spec:
+
+1. `branches` defines the list of `filter` and `subscriber` pairs, one per branch,
+   and optionally a `reply` object. For each branch:
+   1. (optional) the `filter` is evaluated and when it returns an event the `subscriber` is
+      executed. Both `filter` and `subscriber` must be `Callable`.
+   1. the event returned by the `subscriber` is sent to the branch `reply`
+      object. When the `reply` is empty, the event is sent to the `spec.reply`
+      object (see below).
+1. (optional) `channelTemplate` defines the Template which will be used to
+   create `Channel`s.
+1. (optional) `reply` defines where the result of each branch is sent to when
+   the branch does not have its own `reply` object.
+
+### Parallel Status
+
+Parallel has three parts for the Status:
+
+1. `conditions` which details the overall status of the Parallel object
+1. `ingressChannelStatus` and `branchesStatuses` which convey the status of
+   underlying `Channel` and `Subscription` resource that are created as part of
+   this Parallel.
+1. `address` which is exposed so that Parallel can be used where Addressable can
+   be used. Sending to this address will target the `Channel` which is fronting
+   this Parallel (same as `ingressChannelStatus`).
+
+## Examples
+
+Learn how to use Parallel by following the [examples](./samples/parallel/README.md)

docs/eventing/parallel.md

@@ -1,12 +1,12 @@
-The following examples will help you understand how to use Choice to describe
+The following examples will help you understand how to use Parallel to describe
 various flows.
 
 ## Prerequisites
 
 All examples require:
 
 - A Kubernetes cluster with
-  - Knative Eventing v0.8+
+  - Knative Eventing v0.9+
   - Knative Service v0.8+
 
 All examples are using the
@@ -23,5 +23,5 @@ trivial filtering, transformation and routing of the incoming events.
 
 The examples are:
 
-- [Choice with multiple cases and global reply](./multiple-cases/README.md)
-- [Choice with mutually exclusive cases](./mutual-exclusivity/README.md)
+- [Parallel with multiple branches and global reply](./multiple-branches/README.md)
+- [Parallel with mutually exclusive cases](./mutual-exclusivity/README.md)

docs/eventing/samples/choice/README.md renamed to docs/eventing/samples/parallel/README.md

@@ -1,6 +1,6 @@
 ---
-title: "Choice Example"
-linkTitle: "Choice"
+title: "Parallel Example"
+linkTitle: "Parallel"
 weight: 10
 type: "docs"
 ---

docs/eventing/samples/choice/_index.md renamed to docs/eventing/samples/parallel/_index.md

@@ -1,9 +1,9 @@
-We are going to create a Choice with two cases:
+We are going to create a Parallel with two branches:
 
-- the first case accepts events with a time that is is even
-- the second case accepts events with a time that is is odd
+- the first branch accepts events with a time that is is even
+- the second branch accepts events with a time that is is odd
 
-The events produced by each case are then sent to the `event-display` service.
+The events produced by each branch are then sent to the `event-display` service.
 
 ## Prerequisites
 
@@ -12,7 +12,7 @@ Please refer to the sample overview for the [prerequisites](../README.md).
 ### Create the Knative Services
 
 Let's first create the filter and transformer services that we will use in our
-Choice.
+Parallel.
 
 ```yaml
 apiVersion: serving.knative.dev/v1alpha1
@@ -78,20 +78,20 @@ spec:
 kubectl create -f ./filters.yaml -f ./transformers.yaml
 ```
 
-### Create the Choice
+### Create the Parallel
 
-The `choice.yaml` file contains the specifications for creating the Choice.
+The `parallel.yaml` file contains the specifications for creating the Parallel.
 
 ```yaml
 apiVersion: messaging.knative.dev/v1alpha1
-kind: Choice
+kind: Parallel
 metadata:
-  name: odd-even-choice
+  name: odd-even-parallel
 spec:
   channelTemplate:
     apiVersion: messaging.knative.dev/v1alpha1
     kind: InMemoryChannel
-  cases:
+  branches:
     - filter:
         ref:
           apiVersion: serving.knative.dev/v1alpha1
@@ -119,10 +119,10 @@ spec:
 ```
 
 ```shell
-kubectl create -f ./choice.yaml
+kubectl create -f ./parallel.yaml
 ```
 
-### Create the CronJobSource targeting the Choice
+### Create the CronJobSource targeting the Parallel
 
 This will create a CronJobSource which will send a CloudEvent with {"message":
 "Even or odd?"} as the data payload every minute.
@@ -137,8 +137,8 @@ spec:
   data: '{"message": "Even or odd?"}'
   sink:
     apiVersion: messaging.knative.dev/v1alpha1
-    kind: Choice
-    name: odd-even-choice
+    kind: Parallel
+    name: odd-even-parallel
 ```
 
 ```shell
@@ -166,7 +166,7 @@ Context Attributes,
   time: 2019-07-31T18:10:00.000309586Z
   datacontenttype: application/json; charset=utf-8
 Extensions,
-  knativehistory: odd-even-choice-kn-choice-0-kn-channel.default.svc.cluster.local, odd-even-choice-kn-choice-kn-channel.default.svc.cluster.local
+  knativehistory: odd-even-parallel-kn-parallel-0-kn-channel.default.svc.cluster.local, odd-even-parallel-kn-parallel-kn-channel.default.svc.cluster.local
 Data,
   {
     "message": "we are even!"
@@ -181,7 +181,7 @@ Context Attributes,
   time: 2019-07-31T18:11:00.002649881Z
   datacontenttype: application/json; charset=utf-8
 Extensions,
-  knativehistory: odd-even-choice-kn-choice-1-kn-channel.default.svc.cluster.local, odd-even-choice-kn-choice-kn-channel.default.svc.cluster.local
+  knativehistory: odd-even-parallel-kn-parallel-1-kn-channel.default.svc.cluster.local, odd-even-parallel-kn-parallel-kn-channel.default.svc.cluster.local
 Data,
   {
     "message": "this is odd!"

docs/eventing/samples/choice/multiple-cases/README.md renamed to docs/eventing/samples/parallel/multiple-branches/README.md

@@ -7,5 +7,5 @@ spec:
   data: '{"message": "Even or odd?"}'
   sink:
     apiVersion: messaging.knative.dev/v1alpha1
-    kind: Choice
-    name: odd-even-choice
+    kind: Parallel
+    name: odd-even-parallel