Componenttrait composing and trait CR naming design

Add the design docs for OAM Kubernetes Runtime PR
crossplane/oam-kubernetes-runtime#305

design/vela-core/componenttrait-composing-and-trait-CR-naming.md

@@ -0,0 +1,124 @@
+# ComponentTrait Composing and Trait CR Naming
+
+* Owner: Jianbo Sun (@wonderflow), Zhou Zheng Xi (@zzxwill)
+* Reviewers: KubeVela/Crossplane Maintainers
+* Status: Draft
+
+## Background
+
+With the evolution of TraitDefinition, definition name can be short and simple without group and kind information,
+and two TraitDefinitions can both refer to the same Trait CRD. So it's necessary to specify how to compose ComponentTrait
+in ApplicationConfiguration and to set the CR name in a friendly way.
+
+## Several ways to compose ComponentTrait in ApplicationConfiguration
+
+- If the name of TraitDefinition is the same as that of Trait CRD
+
+As shown in [OAM Kubernetes Runtime examples](https://github.com/crossplane/oam-kubernetes-runtime/blob/master/examples/containerized-workload/sample_application_config.yaml), the normal way to compose ComponentTrait is as below.
+
+```
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: example-appconfig
+spec:
+  components:
+    - componentName: example-component
+      traits:
+        - trait:
+            apiVersion: core.oam.dev/v1alpha2
+            kind: ManualScalerTrait
+            spec:
+              replicaCount: 3
+```
+
+- If the name of TraitDefinition is different to that of Trait CRD
+
+The definition name `autoscale` is different to the trait name `autoscalers.standard.oam.dev`, we have two ways to compose ComponentTrait.
+
+```
+apiVersion: core.oam.dev/v1alpha2
+kind: TraitDefinition
+metadata:
+  name: autoscale
+spec:
+  definitionRef:
+    name: autoscalers.standard.oam.dev
+```
+
+1) Use label `trait.oam.dev/type`
+
+```
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: example-appconfig
+spec:
+  components: example-component
+  traits:
+    - trait:
+        apiVersion: standard.oam.dev/v1alpha2
+        kind: Autoscalers
+        metadata:
+          labels:
+            - oam.TraitTypeLabel: "autoscale"
+        spec:
+          replicaCount: 3
+```
+
+When rendering trait, the TraitDefinition could be retrieved by the label.
+
+2) Use `name` field
+
+```
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: example-appconfig
+spec:
+  components: example-component
+  traits:
+    - trait:
+        apiVersion: standard.oam.dev/v1alpha2
+        kind: Autoscalers
+        name: autoscale
+        spec:
+          replicaCount: 3
+```
+
+The mutating handler will, at the very beginning,  convert `name:autoscale` to the labels above.
+
+In summary, among these two ways to compose ComponentTrait, using labeling is recommended.
+
+While in KubeVela, you don't need to worry about either `label` or `name`, just use command `vela TraitType` or `vela up` to attach the trait to
+a component.
+
+## Set the CR name in a friendly way
+
+Before OAM Kubernetes Runtime release v0.3.2, we named all trait name in the format of `${ComponentName}-trait-${HashTag}`. This will lead to confusions
+when listing CRs of all Traits of a component. So we propose to change the name to `${ComponentName}-${TraitDefinitionName}-${HashTag}`.
+
+If the name of a TraitDefinition is in short style, like `autoscale`, we name the trait CR to `example-component-autoscale-xyzfa32r`.
+
+```
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: example-appconfig
+spec:
+  components: example-component
+  traits:
+    - trait:
+        apiVersion: standard.oam.dev/v1alpha2
+        kind: Autoscalers
+        metadata:
+          labels:
+            - oam.TraitTypeLabel: "autoscale"
+        spec:
+          replicaCount: 3
+```
+
+If the name is the same as the CRD name, like `manualscalertraits.core.oam.dev`, we name it to `example-component-manualscalertraits-rq234rrw`
+by choosing the first part.
+
+After OAM Kubernetes Runtime is upgraded, the old trait CR name `example-component-trait-uewf77eu` will stay unchanged for previous version compatibility.