refine based on initial feedback

doc/design/resource-dependency.md

@@ -122,17 +122,17 @@ To achieve this, we propose:
       fromDataOutput: mysql-conn-secret # check below DataOutput of the same name
     ```
 
-   The above DataInputs will be json-marshaled and put into an annotation key `core.oam.dev/datainputs` of my-app Deployment:
+   The above DataInputs will be json-marshaled and put into an annotation key `core.oam.dev/datainputs` of my-web workload:
 
     ```yaml
-    kind: Deployment
+    kind: MyWorkload
     metadata:
-      name: my-app
+      name: my-web
       annotations:
         "core.oam.dev/datainputs": "[{\"toFieldPaths\": [\"spec.connSecret\"],\"fromDataOutput\": \"mysql-conn-secret\"}]"
     ```
 
-    Note that my-app won't be created since it has DataInputs dependency to satisfy.
+    Note that my-web won't be created since it has a DataInputs dependency to satisfy.
 
 2. Add a new CRD `DataOutput` with the following definition:
 
@@ -183,7 +183,7 @@ To achieve this, we propose:
       fieldPath: "status.connSecret"
     ```
 
-    In this case, the OAM runtime will automatically build a dependency between the `my-app` and `my-rds`.
+    In this case, the OAM runtime will automatically build a dependency between the `my-web` and `my-rds`.
 
     It will wait until `my-rds` object's field `status.connSecret` has value, and marks the DataOutput status ready:
 
@@ -207,40 +207,48 @@ To achieve this, we propose:
     ```
 
     At this point, the dependency has been satisfied.
-    The OAM runtime will create `my-app` object with corresponding values passed to its fields.
+    The OAM runtime will create `my-web` object with corresponding values passed to its fields.
 
     ```yaml
-    kind: Deployment
+    kind: MyWorkload
     metadata:
-      name: my-app
+      name: my-web
       ..
     spec:
       connSecret: mysql-conn
     ```
 
-3. In OAM Component we put a special syntax sugar in `Parameters` fields:
-  as long asthe name of the Parameter matches the name of the DataOutput, it becomes a DataInput.
+3. Below we show how to combine the above concepts (DataInput, DataOutput) into OAM.
 
-    For example, the following parameter mysql-conn-secret in Component matches the name of DataOutput trait
-    in the same ApplicationConfiguration.
+    In OAM Component we put a syntax-sugar on existing `Parameters` fields:
+    as long as the name of the Parameter matches the name of the DataOutput, it becomes a DataInput.
+    For example, the following parameter mysql-conn-secret in Component matches the name of DataOutput trait.
 
     ```yaml
     kind: Component
     metadata:
-      name: my-app
+      name: my-web
     spec:
       workload:
-        kind: Deployment
+        kind: MyWorkload
         metadata:
-          name: my-app
+          name: my-web
       parameters:
       - name: mysql-conn-secret # this matches the name of DataOutput
         fieldPaths: ["spec.connSecret"]
-    
+    ---
+    kind: Component
+    metadata:
+      name: my-rds
+    spec:
+      workload:
+        kind: RDSInstance
+        metadata:
+          name: my-rds
     ---
     # In ApplicationConfiguration
     components:
-    - componentName: my-app
+    - componentName: my-web
       traits:
       - trait:
           apiVersion: core.oam.dev/v1alpha2
@@ -253,23 +261,42 @@ To achieve this, we propose:
               kind: RDSInstance
               name: my-rds
             fieldPath: "status.connSecret"
+    - componentName: my-rds
     ```
 
-    In this case, the OAM runtime will build a dependency from my-app to my-rds,
-    wait until the field data ready, and create the workload patched with DataInputs annotation.
+    The DataOutput trait is a system trait which OAM runtime understands and makes use of to build dependency graph.
+    In this case, OAM runtime will build a dependency from my-web to my-rds,
+    wait until the field data in my-rds resource ready, and create the my-web workload patched with inputs.
 
     ```yaml
-    kind: Deployment
+    kind: MyWorkload
     metadata:
-      name: my-app
+      name: my-web
       annotations:
         "core.oam.dev/datainputs": "[{\"toFieldPaths\": [\"spec.connSecret\"],\"fromDataOutput\": \"mysql-conn-secret\"}]"
+    spec:
+      connSecret: mysql-conn # patched by OAM runtime
     ```
 
 ### Limitations
 
 All the resources in the dependency graph should be created and managed by OAM runtime.
 
+### Upgrade consideration
+
+Currently the main thing is modeled as a trait i.e. DataOutput trait.
+Once this feature becomes popular, we will change it into more native fields of OAM spec in the future.
+Here we discuss an idea to upgrade if that happens.
+
+The functionality in OAM runtime is an internal implementation.
+Either DataOutput trait or a potential field `outputs` are representation layer.
+We could map either into underlying DataOutput resources.
+
+It's inevitable that an intermediate phase where both exists could happen.
+But they don't both exist in the same ApplicationConfiguration.
+Only one could exist and we only map that into underlying implementation.
+
+
 ## Solution examples
 
 In this section we are providing more solution examples for dependency use cases.
@@ -280,7 +307,7 @@ In this section we are providing more solution examples for dependency use cases
 
     ```yaml
     components:
-    - componentName: my-app
+    - componentName: my-web
       traits:
       - trait:
           apiVersion: core.oam.dev/v1alpha1
@@ -307,7 +334,7 @@ In this section we are providing more solution examples for dependency use cases
     ```yaml
     kind: Component
     metadata:
-      name: my-app
+      name: my-web
     spec:
       parameters:
       - name: my-secret-binding