Merge pull request #637 from wonderflow/display

add tips about vela install capability not ready instead of directly fail

.github/workflows/dashboard.yml

@@ -4,6 +4,10 @@ on:
   push:
     branches: [ master ]
   pull_request:
+    branches: [master]
+    paths-ignore:
+    - 'docs/**'
+    - '**.md'
 defaults:
   run:
     working-directory: ./dashboard

.github/workflows/e2e.yml

@@ -5,6 +5,9 @@ on:
     branches: [master]
   pull_request:
     branches: [master]
+    paths-ignore:
+    - 'docs/**'
+    - '**.md'
 
 jobs:
   build:
@@ -19,7 +22,7 @@ jobs:
           go get -v -t -d ./...
 
       - name: Setup Kind Cluster
-        uses: engineerd/setup-kind@v0.4.0
+        uses: engineerd/setup-kind@v0.5.0
         with:
           version: "v0.7.0"
           skipClusterCreation: true

.github/workflows/go.yml

@@ -5,6 +5,9 @@ on:
     branches: [master]
   pull_request:
     branches: [master]
+    paths-ignore:
+    - 'docs/**'
+    - '**.md'
 
 jobs:
   build:
@@ -25,12 +28,12 @@ jobs:
           sudo apt-get install -y golang-ginkgo-dev
 
       - name: Setup Kind Cluster
-        uses: engineerd/setup-kind@v0.4.0
+        uses: engineerd/setup-kind@v0.5.0
         with:
           version: "v0.7.0"
 
       - name: install Kubebuilder
-        uses: RyanSiu1995/kubebuilder-action@v1
+        uses: wonderflow/kubebuilder-action@v1.1
 
       - name: Run Make test
         run: make test

CONTRIBUTING.md

@@ -14,6 +14,8 @@ contributing to `kubevela` or build a PoC (Proof of Concept).
 3. ginkgo 1.14.0+ (just for [E2E test](https://github.com/oam-dev/kubevela/blob/master/DEVELOPMENT.md#e2e-test))
 4. golangci-lint 1.31.0+, it will install automatically if you run `make`, you can [install it manually](https://golangci-lint.run/usage/install/#local-installation) if the installation is too slow.
 
+We also recommend you to learn about KubeVela's [design](docs/en/design.md) before dive into its code.
+
 ## Build
 
 * Clone this project

Makefile

@@ -1,14 +1,14 @@
 # Vela version
 VELA_VERSION ?= 0.1.0
 # Repo info
-GIT_COMMIT ?= git-$(shell git rev-parse --short HEAD)
-VELA_VERSION_VAR := github.com/oam-dev/kubevela/version.VelaVersion
+GIT_COMMIT          ?= git-$(shell git rev-parse --short HEAD)
+VELA_VERSION_VAR    := github.com/oam-dev/kubevela/version.VelaVersion
 VELA_GITVERSION_VAR := github.com/oam-dev/kubevela/version.GitRevision
-LDFLAGS ?= "-X $(VELA_VERSION_VAR)=$(VELA_VERSION) -X $(VELA_GITVERSION_VAR)=$(GIT_COMMIT)"
+LDFLAGS             ?= "-X $(VELA_VERSION_VAR)=$(VELA_VERSION) -X $(VELA_GITVERSION_VAR)=$(GIT_COMMIT)"
 
-GOX      = go run github.com/mitchellh/gox
-TARGETS  := darwin/amd64 linux/amd64 windows/amd64
-DIST_DIRS       := find * -type d -exec
+GOX         = go run github.com/mitchellh/gox
+TARGETS     := darwin/amd64 linux/amd64 windows/amd64
+DIST_DIRS   := find * -type d -exec
 
 # Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
 ifeq (,$(shell go env GOBIN))
@@ -64,8 +64,9 @@ run: fmt vet
 	go run ./cmd/core/main.go
 
 # Run go fmt against code
-fmt:
+fmt: goimports
 	go fmt ./...
+	$(GOIMPORTS) -local github.com/oam-dev/kubevela -w ./pkg ./cmd
 	./hack/cue-fmt.sh
 
 # Run go vet against code
@@ -126,10 +127,12 @@ core-run: generate fmt vet manifests
 
 # Install CRDs and Definitions of Vela Core into a cluster, this is for develop convenient.
 core-install: manifests
+	kubectl apply -f hack/namespace.yaml
 	kubectl apply -f charts/vela-core/crds/
 	kubectl apply -f charts/vela-core/templates/defwithtemplate/
 	kubectl apply -f charts/vela-core/templates/definitions/
-	bin/vela system update
+	kubectl apply -f charts/vela-core/templates/velaConfig.yaml
+	bin/vela workloads
 
 # Uninstall CRDs and Definitions of Vela Core from a cluster, this is for develop convenient.
 core-uninstall: manifests
@@ -140,6 +143,7 @@ core-uninstall: manifests
 # Generate manifests e.g. CRD, RBAC etc.
 manifests: controller-gen
 	$(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=charts/vela-core/crds
+	go generate $(foreach t,pkg api,./$(t)/...)
 	./hack/vela-templates/gen_definitions.sh
 
 # Generate code
@@ -182,3 +186,15 @@ GOLANGCILINT=$(GOBIN)/golangci-lint
 else
 GOLANGCILINT=$(shell which golangci-lint)
 endif
+
+.PHONY: goimports
+goimports:
+ifeq (, $(shell which goimports))
+	@{ \
+	set -e ;\
+	GO111MODULE=off go get -u golang.org/x/tools/cmd/goimports ;\
+	}
+GOIMPORTS=$(GOBIN)/goimports
+else
+GOIMPORTS=$(shell which goimports)
+endif

README.md

@@ -1,4 +1,13 @@
-![alt](resources/KubeVela-03.png)
+![Build status](https://github.com/oam-dev/kubevela/workflows/E2E/badge.svg)
+[![Go Report Card](https://goreportcard.com/badge/github.com/oam-dev/kubevela)](https://goreportcard.com/report/github.com/oam-dev/kubevela)
+![Docker Pulls](https://img.shields.io/docker/pulls/oamdev/vela-core)
+[![codecov](https://codecov.io/gh/oam-dev/kubevela/branch/master/graph/badge.svg)](https://codecov.io/gh/oam-dev/kubevela)
+[![LICENSE](https://img.shields.io/github/license/oam-dev/kubevela.svg?style=flat-square)](/LICENSE)
+[![Releases](https://img.shields.io/github/release/oam-dev/kubevela/all.svg?style=flat-square)](https://github.com/oam-dev/kubevela/releases)
+[![TODOs](https://img.shields.io/endpoint?url=https://api.tickgit.com/badge?repo=github.com/oam-dev/kubevela)](https://www.tickgit.com/browse?repo=github.com/oam-dev/kubevela)
+[![Twitter](https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Ftwitter.com%2Foam_dev)](https://twitter.com/oam_dev)
+
+![alt](docs/resources/KubeVela-03.png)
 
 *Make shipping applications more enjoyable.*
 
@@ -15,11 +24,11 @@ For platform builders, KubeVela serves as a framework that empowers them to crea
 
 ## Quick Start
 
-Quick start guides are available on [this section](docs/quick-start.md).
+Quick start guides are available on [this section](https://kubevela.io/#/en/quick-start).
 
 ## Documentation
 
-To see full documentation, visit [kubevela.io](https://kubevela.io/).
+For full documentation, please visit the KubeVela website: [https://kubevela.io](https://kubevela.io/).
 
 ## Contributing
 Check out [CONTRIBUTING](./CONTRIBUTING.md) to see how to develop with KubeVela.

api/api.go

@@ -0,0 +1,2 @@
+// package api contains all api types of KubeVela
+package api

api/core.oam.dev/v1alpha2/appdeploy_types.go

@@ -34,10 +34,10 @@ type ApplicationDeploymentStatus struct {
 	runtimev1alpha1.ConditionedStatus `json:",inline"`
 }
 
+// ApplicationDeployment is the Schema for the ApplicationDeployment API
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:categories={oam}
 // +kubebuilder:subresource:status
-// ApplicationDeployment is the Schema for the ApplicationDeployment API
 type ApplicationDeployment struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -46,8 +46,8 @@ type ApplicationDeployment struct {
 	Status ApplicationDeploymentStatus `json:"status,omitempty"`
 }
 
-// +kubebuilder:object:root=true
 // ApplicationDeploymentList contains a list of ApplicationDeployment
+// +kubebuilder:object:root=true
 type ApplicationDeploymentList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/generate.go

@@ -0,0 +1,8 @@
+// +build generate
+
+// See the below link for details on what is happening here.
+// https://github.com/golang/go/wiki/Modules#how-can-i-track-tool-dependencies-for-a-module
+
+//go:generate go run ../hack/crd/update.go ../charts/vela-core/crds/
+
+package api

api/types/args.go

@@ -5,6 +5,7 @@ import (
 	"k8s.io/client-go/rest"
 )
 
+// Args is args for controller-runtime client
 type Args struct {
 	Config *rest.Config
 	Schema *runtime.Scheme

api/types/capability.go

@@ -26,12 +26,14 @@ import (
 	"k8s.io/apimachinery/pkg/runtime"
 )
 
+// Source record the source of Capability
 type Source struct {
 	RepoName  string `json:"repoName"`
 	ChartName string `json:"chartName,omitempty"`
 }
 
-type CrdInfo struct {
+// CRDInfo record the CRD info of the Capability
+type CRDInfo struct {
 	APIVersion string `json:"apiVersion"`
 	Kind       string `json:"kind"`
 }
@@ -55,29 +57,38 @@ type Capability struct {
 	// Plugin Source
 	Source  *Source       `json:"source,omitempty"`
 	Install *Installation `json:"install,omitempty"`
-	CrdInfo *CrdInfo      `json:"crdInfo,omitempty"`
+	CrdInfo *CRDInfo      `json:"crdInfo,omitempty"`
 }
 
+// Chart defines all necessary information to install a whole chart
 type Chart struct {
-	Repo      string `json:"repo"`
-	URL       string `json:"url"`
-	Name      string `json:"name"`
-	Namespace string `json:"namespace,omitempty"`
-	Version   string `json:"version"`
+	Repo      string                 `json:"repo"`
+	URL       string                 `json:"url"`
+	Name      string                 `json:"name"`
+	Namespace string                 `json:"namespace,omitempty"`
+	Version   string                 `json:"version"`
+	Values    map[string]interface{} `json:"values"`
 }
 
+// Installation defines the installation method for this Capability, currently only helm is supported
 type Installation struct {
 	Helm Chart `json:"helm"`
+	//TODO(wonderflow) add raw yaml file support for install capability
 }
 
+// CapType defines the type of capability
 type CapType string
 
 const (
+	// TypeWorkload represents OAM Workload
 	TypeWorkload CapType = "workload"
-	TypeTrait    CapType = "trait"
-	TypeScope    CapType = "scope"
+	// TypeTrait represents OAM Trait
+	TypeTrait CapType = "trait"
+	// TypeScope represent OAM Scope
+	TypeScope CapType = "scope"
 )
 
+// Parameter defines a parameter for cli from capability template
 type Parameter struct {
 	Name     string      `json:"name"`
 	Short    string      `json:"short,omitempty"`
@@ -92,11 +103,8 @@ type Parameter struct {
 func ConvertTemplateJSON2Object(in *runtime.RawExtension) (Capability, error) {
 	var t Capability
 	var extension Capability
-	if in == nil {
-		return t, fmt.Errorf("extension field is nil")
-	}
-	if in.Raw == nil {
-		return t, fmt.Errorf("template object is nil")
+	if in == nil || in.Raw == nil {
+		return t, fmt.Errorf("no template found")
 	}
 	err := json.Unmarshal(in.Raw, &extension)
 	if err == nil {
@@ -105,6 +113,7 @@ func ConvertTemplateJSON2Object(in *runtime.RawExtension) (Capability, error) {
 	return t, err
 }
 
+// SetFlagBy set cli flag from Parameter
 func SetFlagBy(flags *pflag.FlagSet, v Parameter) {
 	name := v.Name
 	if v.Alias != "" {
@@ -144,6 +153,7 @@ func SetFlagBy(flags *pflag.FlagSet, v Parameter) {
 	}
 }
 
+// CapabilityCmpOptions will set compare option
 var CapabilityCmpOptions = []cmp.Option{
 	cmp.Comparer(func(a, b Parameter) bool {
 		if a.Name != b.Name || a.Short != b.Short || a.Required != b.Required ||
@@ -188,7 +198,7 @@ var CapabilityCmpOptions = []cmp.Option{
 			case int:
 				va = float64(vala)
 			case float64:
-				va = float64(vala)
+				va = vala
 			}
 			switch valb := b.Default.(type) {
 			case int64:
@@ -198,13 +208,14 @@ var CapabilityCmpOptions = []cmp.Option{
 			case int:
 				vb = float64(valb)
 			case float64:
-				vb = float64(valb)
+				vb = valb
 			}
 			return va == vb
 		}
 		return true
 	})}
 
+// EqualCapability will check whether two capabilities is equal
 func EqualCapability(a, b Capability) bool {
 	return cmp.Equal(a, b, CapabilityCmpOptions...)
 }

api/types/types.go

@@ -1,28 +1,33 @@
 package types
 
 const (
-	DefaultOAMNS               = "vela-system"
-	DefaultOAMReleaseName      = "kubevela"
-	DefaultOAMRuntimeChartName = "vela-core"
-	DefaultOAMVersion          = ">0.0.0-0"
-
-	DefaultEnvName      = "default"
+	// DefaultKubeVelaNS defines the default KubeVela namespace in Kubernetes
+	DefaultKubeVelaNS = "vela-system"
+	// DefaultKubeVelaReleaseName defines the default name of KubeVela Release
+	DefaultKubeVelaReleaseName = "kubevela"
+	// DefaultKubeVelaChartName defines the default chart name of KubeVela, this variable MUST align to the chart name of this repo
+	DefaultKubeVelaChartName = "vela-core"
+	// DefaultKubeVelaVersion defines the default version needed for KubeVela chart
+	DefaultKubeVelaVersion = ">0.0.0-0"
+	// DefaultEnvName defines the default environment name for Apps created by KubeVela
+	DefaultEnvName = "default"
+	// DefaultAppNamespace defines the default K8s namespace for Apps created by KubeVela
 	DefaultAppNamespace = "default"
 )
 
 const (
-	AnnAPIVersion  = "definition.oam.dev/apiVersion"
-	AnnKind        = "definition.oam.dev/kind"
+	// AnnDescription is the annotation which describe what is the capability used for in a WorkloadDefinition/TraitDefinition Object
 	AnnDescription = "definition.oam.dev/description"
-
-	LabelPodSpecable = "workload.oam.dev/podspecable"
 )
 
 const (
+	// StatusDeployed represents the App was deployed
 	StatusDeployed = "Deployed"
-	StatusStaging  = "Staging"
+	// StatusStaging represents the App was changed locally and it's spec is diff from the deployed one, or not deployed at all
+	StatusStaging = "Staging"
 )
 
+// EnvMeta stores the info for app environment
 type EnvMeta struct {
 	Name      string `json:"name"`
 	Namespace string `json:"namespace"`
@@ -35,12 +40,14 @@ type EnvMeta struct {
 }
 
 const (
+	// TagCommandType used for tag cli category
 	TagCommandType = "commandType"
-
-	TypeStart   = "Getting Started"
-	TypeApp     = "Applications"
-	TypeTraits  = "Traits"
-	TypeRelease = "Release"
-	TypeOthers  = "Others"
-	TypeSystem  = "System"
+	// TypeStart defines one category
+	TypeStart = "Getting Started"
+	// TypeApp defines one category
+	TypeApp = "Managing Applications"
+	// TypeCap defines one category
+	TypeCap = "Managing Capabilities"
+	// TypeSystem defines one category
+	TypeSystem = "System"
 )

api/v1alpha1/autoscaler_types.go

@@ -30,9 +30,9 @@ type Protocol string
 // TriggerType defines the type of trigger
 type TriggerType string
 
+// Autoscaler is the Schema for the autoscalers API
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:categories={oam}
-// Autoscaler is the Schema for the autoscalers API
 type Autoscaler struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -41,18 +41,22 @@ type Autoscaler struct {
 	Status AutoscalerStatus `json:"status,omitempty"`
 }
 
+// SetConditions set condition for CR status
 func (as *Autoscaler) SetConditions(c ...v1alpha1.Condition) {
 	as.Status.SetConditions(c...)
 }
 
+// GetCondition get condition from CR status
 func (as *Autoscaler) GetCondition(conditionType v1alpha1.ConditionType) v1alpha1.Condition {
 	return as.Status.GetCondition(conditionType)
 }
 
+// GetWorkloadReference get workload reference
 func (as *Autoscaler) GetWorkloadReference() v1alpha1.TypedReference {
 	return as.Spec.WorkloadReference
 }
 
+// SetWorkloadReference set workload reference
 func (as *Autoscaler) SetWorkloadReference(reference v1alpha1.TypedReference) {
 	as.Spec.WorkloadReference = reference
 }

api/v1alpha1/metricstrait_types.go

@@ -99,20 +99,22 @@ func init() {
 
 var _ oam.Trait = &MetricsTrait{}
 
+// SetConditions for set CR condition
 func (tr *MetricsTrait) SetConditions(c ...runtimev1alpha1.Condition) {
 	tr.Status.SetConditions(c...)
 }
 
+// GetCondition for get CR condition
 func (tr *MetricsTrait) GetCondition(c runtimev1alpha1.ConditionType) runtimev1alpha1.Condition {
 	return tr.Status.GetCondition(c)
 }
 
-// GetWorkloadReference of this ManualScalerTrait.
+// GetWorkloadReference of this MetricsTrait.
 func (tr *MetricsTrait) GetWorkloadReference() runtimev1alpha1.TypedReference {
 	return tr.Spec.WorkloadReference
 }
 
-// SetWorkloadReference of this ManualScalerTrait.
+// SetWorkloadReference of this MetricsTrait.
 func (tr *MetricsTrait) SetWorkloadReference(r runtimev1alpha1.TypedReference) {
 	tr.Spec.WorkloadReference = r
 }

api/v1alpha1/podspecworkload_types.go

@@ -73,10 +73,12 @@ func init() {
 
 var _ oam.Workload = &PodSpecWorkload{}
 
+// SetConditions set condition for this CR
 func (in *PodSpecWorkload) SetConditions(c ...cpv1alpha1.Condition) {
 	in.Status.SetConditions(c...)
 }
 
+// GetCondition set condition for this CR
 func (in *PodSpecWorkload) GetCondition(c cpv1alpha1.ConditionType) cpv1alpha1.Condition {
 	return in.Status.GetCondition(c)
 }

api/v1alpha1/route_types.go

@@ -66,6 +66,7 @@ type Rule struct {
 	Backend *Backend `json:"backend,omitempty"`
 }
 
+// TLS defines certificate issuer and type for mTLS configuration
 type TLS struct {
 	IssuerName string `json:"issuerName,omitempty"`
 
@@ -74,13 +75,17 @@ type TLS struct {
 	Type IssuerType `json:"type,omitempty"`
 }
 
+// IssuerType defines the type of issuer
 type IssuerType string
 
 const (
-	ClusterIssuer   IssuerType = "ClusterIssuer"
+	// ClusterIssuer is a cluster level type of issuer
+	ClusterIssuer IssuerType = "ClusterIssuer"
+	// NamespaceIssuer is the default one
 	NamespaceIssuer IssuerType = "Issuer"
 )
 
+// Backend defines backend configure for route trait.
 // Route will automatically discover podSpec and label for BackendService.
 // If BackendService is already set, discovery won't work.
 // If BackendService is not set, the discovery mechanism will work.
@@ -109,10 +114,10 @@ type RouteStatus struct {
 	runtimev1alpha1.ConditionedStatus `json:",inline"`
 }
 
+// Route is the Schema for the routes API
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:categories={oam}
 // +kubebuilder:subresource:status
-// Route is the Schema for the routes API
 type Route struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -121,8 +126,8 @@ type Route struct {
 	Status RouteStatus `json:"status,omitempty"`
 }
 
-// +kubebuilder:object:root=true
 // RouteList contains a list of Route
+// +kubebuilder:object:root=true
 type RouteList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
@@ -135,20 +140,22 @@ func init() {
 
 var _ oam.Trait = &Route{}
 
+// SetConditions set condition for CR status
 func (r *Route) SetConditions(c ...runtimev1alpha1.Condition) {
 	r.Status.SetConditions(c...)
 }
 
+// GetCondition get condition from CR status
 func (r *Route) GetCondition(c runtimev1alpha1.ConditionType) runtimev1alpha1.Condition {
 	return r.Status.GetCondition(c)
 }
 
-// GetWorkloadReference of this ManualScalerTrait.
+// GetWorkloadReference of this Route Trait.
 func (r *Route) GetWorkloadReference() runtimev1alpha1.TypedReference {
 	return r.Spec.WorkloadReference
 }
 
-// SetWorkloadReference of this ManualScalerTrait.
+// SetWorkloadReference of this Route Trait.
 func (r *Route) SetWorkloadReference(rt runtimev1alpha1.TypedReference) {
 	r.Spec.WorkloadReference = rt
 }

charts/vela-core/crds/standard.oam.dev_podspecworkloads.yaml

@@ -1230,6 +1230,7 @@ spec:
                                   can be referred to by services.
                                 type: string
                               protocol:
+                                default: TCP
                                 description: Protocol for port. Must be UDP, TCP,
                                   or SCTP. Defaults to "TCP".
                                 type: string
@@ -2364,6 +2365,7 @@ spec:
                                   can be referred to by services.
                                 type: string
                               protocol:
+                                default: TCP
                                 description: Protocol for port. Must be UDP, TCP,
                                   or SCTP. Defaults to "TCP".
                                 type: string
@@ -3503,6 +3505,7 @@ spec:
                                   can be referred to by services.
                                 type: string
                               protocol:
+                                default: TCP
                                 description: Protocol for port. Must be UDP, TCP,
                                   or SCTP. Defaults to "TCP".
                                 type: string

charts/vela-core/templates/definitions/healthscopes.yaml

@@ -2,9 +2,6 @@ apiVersion: core.oam.dev/v1alpha2
 kind: ScopeDefinition
 metadata:
   name: healthscopes.core.oam.dev
-  annotations:
-    definition.oam.dev/apiVersion: core.oam.dev/v1alpha2
-    definition.oam.dev/kind: HealthScope
   namespace: default
 spec:
   workloadRefsPath: spec.workloadRefs

charts/vela-core/templates/defwithtemplate/autoscale.yaml

@@ -3,33 +3,31 @@ kind: TraitDefinition
 metadata:
   name: autoscale
   annotations:
-    definition.oam.dev/apiVersion: standard.oam.dev/v1alpha1
-    definition.oam.dev/kind: Autoscaler
-    definition.oam.dev/description: "Automatically scale workloads"
+    definition.oam.dev/description: "Automatically scale the app following certain triggers or metrics"
 spec:
   appliesToWorkloads:
     - webservice
-    - backend
-    - deployments.apps
-    - podspecworkload
+    - worker
   workloadRefPath: spec.workloadRef
   definitionRef:
     name: autoscalers.standard.oam.dev
   extension:
     template: |
+      import "strconv"
+      
       output: {
       	apiVersion: "standard.oam.dev/v1alpha1"
       	kind:       "Autoscaler"
       	spec: {
       		minReplicas: parameter.min
       		maxReplicas: parameter.max
-      		if parameter["cpu"] != _|_ && parameter["cron"] != _|_ {
+      		if parameter["cpuPercent"] != _|_ && parameter["cron"] != _|_ {
       			triggers: [cpuScaler, cronScaler]
       		}
-      		if parameter["cpu"] != _|_ && parameter["cron"] == _|_ {
+      		if parameter["cpuPercent"] != _|_ && parameter["cron"] == _|_ {
       			triggers: [cpuScaler]
       		}
-      		if parameter["cpu"] == _|_ && parameter["cron"] != _|_ {
+      		if parameter["cpuPercent"] == _|_ && parameter["cron"] != _|_ {
       			triggers: [cronScaler]
       		}
       	}
@@ -39,16 +37,23 @@ spec:
       	type: "cpu"
       	condition: {
       		type: "Utilization"
-      		if parameter["cpu"] != _|_ {
-      			value: parameter.cpu
+      		if parameter["cpuPercent"] != _|_ {
+      			// Temporarily use `strconv` for type converting. This bug will be fixed in kubevela#585
+      			value: strconv.FormatInt(parameter.cpuPercent, 10)
       		}
       	}
       }
       
       cronScaler: {
       	type: "cron"
-      	if parameter["cron"] != _|_ {
-      		condition: parameter.cron
+      	if parameter["cron"] != _|_ && parameter.cron["replicas"] != _|_ {
+      		condition: {
+      			startAt:  parameter.cron.startAt
+      			duration: parameter.cron.duration
+      			days:     parameter.cron.days
+      			replicas: strconv.FormatInt(parameter.cron.replicas, 10)
+      			timezone: parameter.cron.timezone
+      		}
       	}
       }
       
@@ -58,15 +63,19 @@ spec:
       	// +usage=maximal replicas of the workload
       	max: int
       	// +usage=specify the value for CPU utilization, like 80, which means 80%
-      	cpu?: string
+      	// +alias=cpu-percent
+      	cpuPercent?: int
       	// +usage=just for `appfile`, not available for Cli usage
       	cron?: {
-      		startAt:  string
+      		// +usage=the time to start scaling, like `08:00`
+      		startAt: string
+      		// +usage=for how long the scaling will last
       		duration: string
       		// +usage=several workdays or weekends, like "Monday, Tuesday"
-      		days:     string
-      		replicas: string
-      		// +usage=timezone, like "America/Seattle"
+      		days: string
+      		// +usage=the target replicas to be scaled to
+      		replicas: int
+      		// +usage=timezone, like "America/Los_Angeles"
       		timezone: string
       	}
       }

charts/vela-core/templates/defwithtemplate/manualscale.yaml

@@ -2,15 +2,12 @@ apiVersion: core.oam.dev/v1alpha2
 kind: TraitDefinition
 metadata:
   annotations:
-    definition.oam.dev/apiVersion: core.oam.dev/v1alpha2
-    definition.oam.dev/kind: ManualScalerTrait
-    definition.oam.dev/description: "Scale replica for workload"
+    definition.oam.dev/description: "Manually scale the app"
   name: scaler
 spec:
   appliesToWorkloads:
     - webservice
-    - containerizedworkloads.core.oam.dev
-    - deployments.apps
+    - worker
   definitionRef:
     name: manualscalertraits.core.oam.dev
   workloadRefPath: spec.workloadRef
@@ -20,11 +17,11 @@ spec:
       	apiVersion: "core.oam.dev/v1alpha2"
       	kind:       "ManualScalerTrait"
       	spec: {
-      		replicaCount: parameter.replica
+      		replicaCount: parameter.replicas
       	}
       }
       parameter: {
       	//+short=r
-      	replica: *1 | int
+      	replicas: *1 | int
       }
       

charts/vela-core/templates/defwithtemplate/metrics.yaml

@@ -1,20 +1,14 @@
 apiVersion: core.oam.dev/v1alpha2
 kind: TraitDefinition
 metadata:
-  name: metric
+  name: metrics
   annotations:
-    definition.oam.dev/apiVersion: standard.oam.dev/v1alpha1
-    definition.oam.dev/kind: MetricsTrait
-    definition.oam.dev/description: "Add metric monitoring for workload"
+    definition.oam.dev/description: "Configure metrics targets to be monitored for the app"
 spec:
   appliesToWorkloads:
     - webservice
     - backend
     - task
-    - containerizedworkloads.core.oam.dev
-    - clonesetworkloads.apps.kruise.io
-    - deployments.apps
-    - statefulsets.apps
   definitionRef:
     name: metricstraits.standard.oam.dev
   workloadRefPath: spec.workloadRef
@@ -31,7 +25,7 @@ spec:
       	// +usage=format of the metrics, default as prometheus
       	// +short=f
       	format: *"prometheus" | string
-      	// +usage= the metric path of the service
+      	// +usage= the metrics path of the service
       	path:    *"/metrics" | string
       	scheme:  *"http" | string
       	enabled: *true | bool

charts/vela-core/templates/defwithtemplate/rollout.yaml

@@ -2,10 +2,11 @@ apiVersion: core.oam.dev/v1alpha2
 kind: TraitDefinition
 metadata:
   name: rollout
+  annotations:
+    definition.oam.dev/description: "Configure canary deployment strategy to release the app"
 spec:
   appliesToWorkloads:
-    - podspecworkload.standard.oam.dev
-    - deployments.apps
+    - webservice
   definitionRef:
     name: canaries.flagger.app
   workloadRefPath: spec.targetRef
@@ -35,16 +36,16 @@ spec:
       			// percentage (0-100)
       			stepWeight: parameter.stepWeight
       			// max replicas scale up to canary
-      			maxReplicas: parameter.replica
+      			maxReplicas: parameter.replicas
       		}
       	}
       }
       parameter: {
-      	// +usage=total replica of the workload
-      	replica: *5 | int
+      	// +usage=total replicas of the workload
+      	replicas: *2 | int
       	// +alias=step-weight
       	// +usage=weight percent of every step in rolling update
-      	stepWeight: *20 | int
+      	stepWeight: *50 | int
       	interval:   *"30s" | string
       }
       

charts/vela-core/templates/defwithtemplate/route.yaml

@@ -3,13 +3,10 @@ kind: TraitDefinition
 metadata:
   name: route
   annotations:
-    definition.oam.dev/apiVersion: standard.oam.dev/v1alpha1
-    definition.oam.dev/kind: Route
-    definition.oam.dev/description: "Add a route for workload"
+    definition.oam.dev/description: "Configure route policy to the app"
 spec:
   appliesToWorkloads:
     - webservice
-    - deployments.apps
   workloadRefPath: spec.workloadRef
   definitionRef:
     name: routes.standard.oam.dev

charts/vela-core/templates/defwithtemplate/task.yaml

@@ -3,9 +3,7 @@ kind: WorkloadDefinition
 metadata:
   name: task
   annotations:
-    definition.oam.dev/apiVersion: "v1"
-    definition.oam.dev/kind: "Job"
-    definition.oam.dev/description: "One-time task/job"
+    definition.oam.dev/description: "One-off task to run a piece of code or script to completion"
 spec:
   definitionRef:
     name: jobs
@@ -34,7 +32,7 @@ spec:
       	// +short=c
       	count: *1 | int
       
-      	// +usage=specify app image
+      	// +usage=Which image would you like to use for your service
       	// +short=i
       	image: string
       

charts/vela-core/templates/defwithtemplate/webservice.yaml

@@ -3,9 +3,7 @@ kind: WorkloadDefinition
 metadata:
   name: webservice
   annotations:
-    definition.oam.dev/apiVersion: "apps/v1"
-    definition.oam.dev/kind: "Deployment"
-    definition.oam.dev/description: "Long running service with network routes"
+    definition.oam.dev/description: "Long-running scalable service with stable endpoint to receive external traffic"
 spec:
   definitionRef:
     name: deployments.apps
@@ -38,24 +36,19 @@ spec:
       					}
       
       					if context["config"] != _|_ {
-      						env: [
-      							for k, v in context.config {
-      								name:  k
-      								value: v
-      							},
-      						]
+      						env: context.config
       					}
       
       					ports: [{
       						containerPort: parameter.port
       					}]
       
-      					if parameter["cpuRequests"] != _|_ {
+      					if parameter["cpu"] != _|_ {
       						resources: {
       							limits:
-      								cpu: parameter.cpuRequests
+      								cpu: parameter.cpu
       							requests:
-      								cpu: parameter.cpuRequests
+      								cpu: parameter.cpu
       						}
       					}
       				}]
@@ -64,15 +57,15 @@ spec:
       	}
       }
       parameter: {
-      	// +usage=specify app image
+      	// +usage=Which image would you like to use for your service
       	// +short=i
       	image: string
       
       	cmd?: [...string]
       
-      	// +usage=specify port for container
+      	// +usage=Which port do you want customer traffic sent to
       	// +short=p
-      	port: *6379 | int
+      	port: *80 | int
       
       	env?: [...{
       		name:   string
@@ -84,8 +77,7 @@ spec:
       			}
       		}
       	}]
-      	// +usage=CPU core requests for the workload
-      	// +alias=cpu-requests
-      	cpuRequests?: string
+      	// +usage=Number of CPU units for the service, like `0.5` (0.5 CPU core), `1` (1 CPU core)
+      	cpu?: string
       }
       

charts/vela-core/templates/defwithtemplate/worker.yaml

@@ -3,9 +3,7 @@ kind: WorkloadDefinition
 metadata:
   name: worker
   annotations:
-    definition.oam.dev/apiVersion: "apps/v1"
-    definition.oam.dev/kind: "Deployment"
-    definition.oam.dev/description: "Backend worker without ports exposed"
+    definition.oam.dev/description: "Long-running scalable backend worker without network endpoint"
 spec:
   definitionRef:
     name: deployments.apps
@@ -43,7 +41,7 @@ spec:
       }
       
       parameter: {
-      	// +usage=specify app image
+      	// +usage=Which image would you like to use for your service
       	// +short=i
       	image: string
       

charts/vela-core/templates/velaConfig.yaml

@@ -2,7 +2,8 @@ apiVersion: v1
 kind: ConfigMap
 metadata:
   name: vela-config
-  namespace: {{ .Release.Namespace }}
+  # TODO: Currently namespace MUST be vela-system
+  namespace: vela-system
 data:
   servicemonitors.monitoring.coreos.com: |
     {

cmd/core/main.go

@@ -209,14 +209,18 @@ func waitWebhookSecretVolume(certDir string, timeout, interval time.Duration) er
 			int64(time.Since(start).Seconds()), int64(timeout.Seconds())))
 		if _, err := os.Stat(certDir); !os.IsNotExist(err) {
 			ready := func() bool {
-				f, _ := os.Open(certDir)
+				f, err := os.Open(filepath.Clean(certDir))
+				if err != nil {
+					return false
+				}
+				// nolint
 				defer f.Close()
 				// check if dir is empty
 				if _, err := f.Readdir(1); err == io.EOF {
 					return false
 				}
 				// check if secret files are empty
-				err := filepath.Walk(certDir, func(path string, info os.FileInfo, err error) error {
+				err = filepath.Walk(certDir, func(path string, info os.FileInfo, err error) error {
 					// even Cert dir is created, cert files are still empty for a while
 					if info.Size() == 0 {
 						return errors.New("secret is not ready")

design/api/vela-restful-api-reference.md

@@ -426,7 +426,7 @@ Please also specify `traits` values if need to attach a trait to several traits
       "workload_name": "poc5",
       "flags": [
         {
-          "name": "replica",
+          "name": "replicas",
           "value": "4"
         }
       ]
@@ -444,7 +444,7 @@ sample response
 	"data": {
 		"name": "podspecworkload",
 		"type": "workload",
-		"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind:       \"PodSpecWorkload\"\n\tmetadata: name: podspecworkload.name\n\tspec: {\n\t\tcontainers: [{\n\t\t\timage: containerized.image\n\t\t\tname:  containerized.name\n\t\t\tports: [{\n\t\t\t\tcontainerPort: containerized.port\n\t\t\t\tprotocol:      \"TCP\"\n\t\t\t\tname:          \"default\"\n\t\t\t}]\n\t\t}]\n\t}\n}\ncontainerized: {\n\tname: string\n\t// +usage=specify app image\n\t// +short=i\n\timage: string\n\t// +usage=specify port for container\n\t// +short=p\n\tport: *6379 | int\n}\n",
+		"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind:       \"PodSpecWorkload\"\n\tmetadata: name: podspecworkload.name\n\tspec: {\n\t\tcontainers: [{\n\t\t\timage: containerized.image\n\t\t\tname:  containerized.name\n\t\t\tports: [{\n\t\t\t\tcontainerPort: containerized.port\n\t\t\t\tprotocol:      \"TCP\"\n\t\t\t\tname:          \"default\"\n\t\t\t}]\n\t\t}]\n\t}\n}\ncontainerized: {\n\tname: string\n\t// +usage=Which image would you like to use for your service\n\t// +short=i\n\timage: string\n\t// +usage=Which port do you want customer traffic sent to\n\t// +short=p\n\tport: *6379 | int\n}\n",
 		"parameters": [{
 			"name": "name",
 			"required": true,
@@ -455,13 +455,13 @@ sample response
 			"short": "i",
 			"required": true,
 			"default": "",
-			"usage": "specify app image",
+			"usage": "Which image would you like to use for your service",
 			"type": 16
 		}, {
 			"name": "port",
 			"short": "p",
 			"default": 6379,
-			"usage": "specify port for container",
+			"usage": "Which port do you want customer traffic sent to",
 			"type": 4
 		}],
 		"definition": "/Users/zhouzhengxi/.vela/capabilities/containerizedworkloads.core.oam.dev.cue",
@@ -492,13 +492,13 @@ sample response
 			"short": "i",
 			"required": true,
 			"default": "",
-			"usage": "specify app image",
+			"usage": "Which image would you like to use for your service",
 			"type": 16
 		}, {
 			"name": "port",
 			"short": "p",
 			"default": 6379,
-			"usage": "specify port for container",
+			"usage": "Which port do you want customer traffic sent to",
 			"type": 4
 		}]
 	}, {
@@ -534,7 +534,7 @@ sample request
   "name": "scale",
   "flags": [
     {
-      "name": "replica",
+      "name": "replicas",
       "value": "4"
     }
   ]
@@ -556,9 +556,9 @@ sample response
 	"data": {
 		"name": "manualscaler",
 		"type": "trait",
-		"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind:       \"ManualScalerTrait\"\n\tspec: {\n\t\treplicaCount: manualscaler.replica\n\t}\n}\nmanualscaler: {\n\t//+short=r\n\treplica: *2 | int\n}\n",
+		"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind:       \"ManualScalerTrait\"\n\tspec: {\n\t\treplicaCount: manualscaler.replicas\n\t}\n}\nmanualscaler: {\n\t//+short=r\n\treplicas: *2 | int\n}\n",
 		"parameters": [{
-			"name": "replica",
+			"name": "replicas",
 			"short": "r",
 			"default": 2,
 			"type": 4
@@ -675,7 +675,7 @@ sample response
 	"data": [{
 		"name": "podspecworkload",
 		"type": "workload",
-		"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind:       \"ContainerizedWorkload\"\n\tmetadata: name: podspecworkload.name\n\tspec: {\n\t\tcontainers: [{\n\t\t\timage: containerized.image\n\t\t\tname:  containerized.name\n\t\t\tports: [{\n\t\t\t\tcontainerPort: containerized.port\n\t\t\t\tprotocol:      \"TCP\"\n\t\t\t\tname:          \"default\"\n\t\t\t}]\n\t\t}]\n\t}\n}\ncontainerized: {\n\tname: string\n\t// +usage=specify app image\n\t// +short=i\n\timage: string\n\t// +usage=specify port for container\n\t// +short=p\n\tport: *6379 | int\n}\n",
+		"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind:       \"ContainerizedWorkload\"\n\tmetadata: name: podspecworkload.name\n\tspec: {\n\t\tcontainers: [{\n\t\t\timage: containerized.image\n\t\t\tname:  containerized.name\n\t\t\tports: [{\n\t\t\t\tcontainerPort: containerized.port\n\t\t\t\tprotocol:      \"TCP\"\n\t\t\t\tname:          \"default\"\n\t\t\t}]\n\t\t}]\n\t}\n}\ncontainerized: {\n\tname: string\n\t// +usage=Which image would you like to use for your service\n\t// +short=i\n\timage: string\n\t// +usage=Which port do you want customer traffic sent to\n\t// +short=p\n\tport: *6379 | int\n}\n",
 		"parameters": [{
 			"name": "name",
 			"required": true,
@@ -686,13 +686,13 @@ sample response
 			"short": "i",
 			"required": true,
 			"default": "",
-			"usage": "specify app image",
+			"usage": "Which image would you like to use for your service",
 			"type": 16
 		}, {
 			"name": "port",
 			"short": "p",
 			"default": 6379,
-			"usage": "specify port for container",
+			"usage": "Which port do you want customer traffic sent to",
 			"type": 4
 		}],
 		"definition": "/Users/zhouzhengxi/.vela/centers/c1/.tmp/containerizedworkloads.core.oam.dev.cue",
@@ -702,9 +702,9 @@ sample response
 	},{
 		"name": "rollout",
 		"type": "trait",
-		"template": "#Template: {\n\tapiVersion: \"extend.oam.dev/v1alpha2\"\n\tkind:       \"SimpleRolloutTrait\"\n\tspec: {\n\t\treplica:        rollout.replica\n\t\tmaxUnavailable: rollout.maxUnavailable\n\t\tbatch:          rollout.batch\n\t}\n}\nrollout: {\n\treplica:        *3 | int\n\tmaxUnavailable: *1 | int\n\tbatch:          *2 | int\n}\n",
+		"template": "#Template: {\n\tapiVersion: \"extend.oam.dev/v1alpha2\"\n\tkind:       \"SimpleRolloutTrait\"\n\tspec: {\n\t\treplicas:        rollout.replicas\n\t\tmaxUnavailable: rollout.maxUnavailable\n\t\tbatch:          rollout.batch\n\t}\n}\nrollout: {\n\treplicas:        *3 | int\n\tmaxUnavailable: *1 | int\n\tbatch:          *2 | int\n}\n",
 		"parameters": [{
-			"name": "replica",
+			"name": "replicas",
 			"default": 3,
 			"type": 4
 		}, {

design/vela-core/appfile-design.md

@@ -50,14 +50,14 @@ services:
       - /mnt/path=sec:my-secret
 
     scale:
-      replica: 2
+      replicas: 2
       auto: # automatic scale up and down based on given metrics
         range: "1-10"
         cpu: 80 # if cpu utilization is above 80%, scale up
         qps: 1000 # if qps is higher than 1k, scale up
 
     canary: # Auto-create canary deployment. Only upgrade after verify successfully.
-      replica: 1 # canary deployment size
+      replicas: 1 # canary deployment size
       headers:
         - "foo:bar.*"
 ```

docs/_sidebar.md

@@ -1,64 +1,76 @@
 - Overview
   - [Introduction](/en/introduction.md)
-  - [Installation](/en/install.md)
-  - [Quick Start](/en/quick-start.md)
-  - [Concepts](/en/concepts.md)
+  - [Getting Started](/en/quick-start.md)
 
-- For Developers
-  - [Setting Up Deployment Environment](/en/developers/config-enviroments.md)
-  - [Initializing Application](/en/developers/app-init.md)
-  - [Setting Routes](/en/developers/set-route.md)
-  - [Setting Auto-scaling Policy](/en/developers/set-autoscale.md)
-  - [Setting Rollout Strategy](/en/developers/set-rollout.md)
-  - [Monitoring Application](/en/developers/set-metrics.md)
-  - [Using Appfile](/en/developers/devex/appfile.md)
-  - [Check Application Logs](/en/developers/check-logs.md)
-  - [Execute Commands in Container](/en/developers/exec-cmd.md)
-  - [Port Forward to Container](/en/developers/port-forward.md)
-  - [Configuring data/env in Application](/en/developers/config-app.md)
-  - [Consuming Cloud Services](/en/developers/cloud-service.md)
-  - [Managing Capabilities](/en/developers/cap-center.md)
-  - [Capability References](/en/developers/references/README.md)
-
-- For Platform Engineers
-  - [Extending KubeVela](/en/platform-engineers/extending-kubevela.md)
-
-- Internals
-  - [Design and Architecture](/en/design.md)
+- Using KubeVela
+  - Appfile
+    - [Learning Appfile](/en/developers/learn-appfile.md)
+  - Operating
+    - [Setting Routes](/en/developers/set-route.md)
+    - [Setting Auto-scaling Policy](/en/developers/set-autoscale.md)
+    - [Setting Rollout Strategy](/en/developers/set-rollout.md)
+    - [Setting Monitoring Policy](/en/developers/set-metrics.md)
+  - Debugging
+    - [Port Forwarding](/en/developers/port-forward.md)
+    - [Check Application Logs](/en/developers/check-logs.md)
+    - [Execute Commands in Container](/en/developers/exec-cmd.md)  
+  - Extensibility
+    - [Managing Capabilities](/en/developers/cap-center.md)
+  - Configuring
+    - [Setting Up Deployment Environment](/en/developers/config-enviroments.md)
+    - [Configuring data/env in Application](/en/developers/config-app.md)
+  - [Alternative Commands](/en/developers/alternative-cmd.md)
+- Extending KubeVela
+  - [Add Workload Type](/en/platform-engineers/workload-type.md)
+  - [Add Trait](/en/platform-engineers/trait.md)
+  - [Add Cloud Services](/en/platform-engineers/cloud-services.md)
 
 - Roadmap
   - [KubeVela Roadmap](/en/roadmap.md)
 
-- CLI Reference
-  - General
-    - [vela config](/en/cli/vela_config.md)
-    - [vela env](/en/cli/vela_env.md)
-    - [vela init](/en/cli/vela_init.md)
-    - [vela install](/en/cli/vela_install.md)
-    - [vela up](/en/cli/vela_up.md)
-    - [vela version](/en/cli/vela_version.md)
-  - Applications
-    - [vela delete](/en/cli/vela_delete.md)
-    - [vela exec](/en/cli/vela_exec.md)
-    - [vela logs](/en/cli/vela_logs.md)
-    - [vela ls](/en/cli/vela_ls.md)
-    - [vela port-forward](/en/cli/vela_port-forward.md)
-    - [vela show](/en/cli/vela_show.md)
-    - [vela status](/en/cli/vela_status.md)
-    - [vela svc](/en/cli/vela_svc.md)
-  - Workload Types
-    - [vela workloads](/en/cli/vela_workloads.md)
-  - Traits
-    - [vela traits](/en/cli/vela_traits.md)
-    - [vela scaler](/en/cli/vela_scaler.md)
-    - [vela route](/en/cli/vela_route.md)
-    - [vela autoscale](/en/cli/vela_autoscale.md)
-    - [vela rollout](/en/cli/vela_rollout.md)
-    - [vela metric](/en/cli/vela_metric.md)
-  - System
-    - [vela completion](/en/cli/vela_completion.md)
-    - [vela dashboard](/en/cli/vela_dashboard.md)
-    - [vela system](/en/cli/vela_system.md)
-    - [vela template](/en/cli/vela_template.md)
-  - Extensibility
-    - [vela cap](/en/cli/vela_cap.md)
+- References
+  - [Concepts and Glossaries](/en/concepts.md)
+  - [Appfile](/en/developers/references/devex/appfile.md)
+  - Capabilities
+    - Workload Types
+      - [Web Service](/en/developers/references/workload-types/web-service.md)
+      - [Task](/en/developers/references/workload-types/task.md)
+      - [Worker](/en/developers/references/workload-types/backend-worker.md)
+    - Traits
+      - [Route](/en/developers/references/traits/route.md)
+      - [Autoscale](/en/developers/references/traits/autoscale.md)
+      - [Rollout](/en/developers/references/traits/rollout.md)
+      - [Metrics](/en/developers/references/traits/metrics.md)
+  - CLI
+    - General
+      - [vela config](/en/cli/vela_config.md)
+      - [vela env](/en/cli/vela_env.md)
+      - [vela init](/en/cli/vela_init.md)
+      - [vela install](/en/cli/vela_install.md)
+      - [vela up](/en/cli/vela_up.md)
+      - [vela version](/en/cli/vela_version.md)
+    - Applications
+      - [vela delete](/en/cli/vela_delete.md)
+      - [vela exec](/en/cli/vela_exec.md)
+      - [vela logs](/en/cli/vela_logs.md)
+      - [vela ls](/en/cli/vela_ls.md)
+      - [vela port-forward](/en/cli/vela_port-forward.md)
+      - [vela show](/en/cli/vela_show.md)
+      - [vela status](/en/cli/vela_status.md)
+      - [vela svc](/en/cli/vela_svc.md)
+    - Workload Types
+      - [vela workloads](/en/cli/vela_workloads.md)
+    - Traits
+      - [vela traits](/en/cli/vela_traits.md)
+      - [vela scaler](/en/cli/vela_scaler.md)
+      - [vela route](/en/cli/vela_route.md)
+      - [vela autoscale](/en/cli/vela_autoscale.md)
+      - [vela rollout](/en/cli/vela_rollout.md)
+      - [vela metrics](/en/cli/vela_metric.md)
+    - System
+      - [vela completion](/en/cli/vela_completion.md)
+      - [vela dashboard](/en/cli/vela_dashboard.md)
+      - [vela system](/en/cli/vela_system.md)
+      - [vela template](/en/cli/vela_template.md)
+    - Extensibility
+      - [vela cap](/en/cli/vela_cap.md)

docs/en/README.md

@@ -1,4 +1,4 @@
-![alt](resources/KubeVela-03.png)
+![alt](../resources/KubeVela-03.png)
 
 *Make shipping applications more enjoyable.*
 

docs/en/cli/vela.md

@@ -20,24 +20,24 @@ vela [flags]
 ### SEE ALSO
 
 * [vela autoscale](vela_autoscale.md)	 - Attach autoscale trait to an app
-* [vela cap](vela_cap.md)	 - Capability Management
+* [vela cap](vela_cap.md)	 - Manage capability centers and installing/uninstalling capabilities
 * [vela completion](vela_completion.md)	 - Output shell completion code for the specified shell (bash or zsh)
-* [vela config](vela_config.md)	 - Manage application configurations
+* [vela config](vela_config.md)	 - Manage configurations
 * [vela dashboard](vela_dashboard.md)	 - Setup API Server and launch Dashboard
-* [vela delete](vela_delete.md)	 - Delete Applications
-* [vela env](vela_env.md)	 - Manage application environments
-* [vela exec](vela_exec.md)	 - Execute a command in a container
-* [vela init](vela_init.md)	 - Init an OAM Application
-* [vela install](vela_install.md)	 - Initialize vela on both client and server
+* [vela delete](vela_delete.md)	 - Delete an application
+* [vela env](vela_env.md)	 - Manage environments
+* [vela exec](vela_exec.md)	 - Execute command in a container
+* [vela init](vela_init.md)	 - Create scaffold for an application
+* [vela install](vela_install.md)	 - Install Vela Core with built-in capabilities
 * [vela logs](vela_logs.md)	 - Tail logs for application
 * [vela ls](vela_ls.md)	 - List services
-* [vela metric](vela_metric.md)	 - Attach metric trait to an app
-* [vela port-forward](vela_port-forward.md)	 - Forward one or more local ports to a Pod of a service in an application
+* [vela metrics](vela_metrics.md)	 - Attach metrics trait to an app
+* [vela port-forward](vela_port-forward.md)	 - Forward local ports to services in an application
 * [vela rollout](vela_rollout.md)	 - Attach rollout trait to an app
 * [vela route](vela_route.md)	 - Attach route trait to an app
 * [vela scaler](vela_scaler.md)	 - Attach scaler trait to an app
-* [vela show](vela_show.md)	 - Get details of an application
-* [vela status](vela_status.md)	 - get status of an application
+* [vela show](vela_show.md)	 - Show details of an application
+* [vela status](vela_status.md)	 - Show status of an application
 * [vela svc](vela_svc.md)	 - Manage services
 * [vela system](vela_system.md)	 - System management utilities
 * [vela template](vela_template.md)	 - Manage templates
@@ -46,4 +46,4 @@ vela [flags]
 * [vela version](vela_version.md)	 - Prints out build version information
 * [vela workloads](vela_workloads.md)	 - List workloads
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_autoscale.md

@@ -19,19 +19,13 @@ vela autoscale frontend
 ### Options
 
 ```
-      --days string       
+      --cpu-percent int   specify the value for CPU utilization, like 80, which means 80%
       --detach            detach trait from service
-      --duration string   
   -h, --help              help for autoscale
-      --maxReplicas int    (default 4)
-      --minReplicas int    (default 1)
-      --name string       
-      --replicas string    (default "2")
+      --max int           maximal replicas of the workload
+      --min int           minimal replicas of the workload
   -s, --staging           only save changes locally without real update application
-      --startAt string    
       --svc string        specify one service belonging to the application
-      --timezone string    (default "Asia/Shanghai")
-      --type string        (default "cron")
 ```
 
 ### Options inherited from parent commands
@@ -44,4 +38,4 @@ vela autoscale frontend
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap.md

@@ -1,10 +1,10 @@
 ## vela cap
 
-Capability Management
+Manage capability centers and installing/uninstalling capabilities
 
 ### Synopsis
 
-Capability Management with config, list, add, remove capabilities
+Manage capability centers and installing/uninstalling capabilities
 
 ### Options
 
@@ -26,4 +26,4 @@ Capability Management with config, list, add, remove capabilities
 * [vela cap ls](vela_cap_ls.md)	 - List capabilities from cap-center
 * [vela cap uninstall](vela_cap_uninstall.md)	 - Uninstall capability from cluster
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_center.md

@@ -20,10 +20,10 @@ Manage Capability Center with config, sync, list
 
 ### SEE ALSO
 
-* [vela cap](vela_cap.md)	 - Capability Management
+* [vela cap](vela_cap.md)	 - Manage capability centers and installing/uninstalling capabilities
 * [vela cap center config](vela_cap_center_config.md)	 - Configure (add if not exist) a capability center, default is local (built-in capabilities)
 * [vela cap center ls](vela_cap_center_ls.md)	 - List all capability centers
 * [vela cap center remove](vela_cap_center_remove.md)	 - Remove specified capability center
 * [vela cap center sync](vela_cap_center_sync.md)	 - Sync capabilities from remote center, default to sync all centers
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_center_config.md

@@ -33,4 +33,4 @@ vela cap center config mycenter https://github.com/oam-dev/catalog/cap-center
 
 * [vela cap center](vela_cap_center.md)	 - Manage Capability Center
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_center_ls.md

@@ -32,4 +32,4 @@ vela cap center ls
 
 * [vela cap center](vela_cap_center.md)	 - Manage Capability Center
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_center_remove.md

@@ -32,4 +32,4 @@ vela cap center remove mycenter
 
 * [vela cap center](vela_cap_center.md)	 - Manage Capability Center
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_center_sync.md

@@ -32,4 +32,4 @@ vela cap center sync mycenter
 
 * [vela cap center](vela_cap_center.md)	 - Manage Capability Center
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_install.md

@@ -31,6 +31,6 @@ vela cap install mycenter/route
 
 ### SEE ALSO
 
-* [vela cap](vela_cap.md)	 - Capability Management
+* [vela cap](vela_cap.md)	 - Manage capability centers and installing/uninstalling capabilities
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_ls.md

@@ -30,6 +30,6 @@ vela cap ls
 
 ### SEE ALSO
 
-* [vela cap](vela_cap.md)	 - Capability Management
+* [vela cap](vela_cap.md)	 - Manage capability centers and installing/uninstalling capabilities
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_cap_uninstall.md

@@ -31,6 +31,6 @@ vela cap uninstall route
 
 ### SEE ALSO
 
-* [vela cap](vela_cap.md)	 - Capability Management
+* [vela cap](vela_cap.md)	 - Manage capability centers and installing/uninstalling capabilities
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_completion.md

@@ -27,4 +27,4 @@ of vela commands.
 * [vela completion bash](vela_completion_bash.md)	 - generate autocompletions script for bash
 * [vela completion zsh](vela_completion_zsh.md)	 - generate autocompletions script for zsh
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_completion_bash.md

@@ -36,4 +36,4 @@ vela completion bash
 
 * [vela completion](vela_completion.md)	 - Output shell completion code for the specified shell (bash or zsh)
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_completion_zsh.md

@@ -33,4 +33,4 @@ vela completion zsh
 
 * [vela completion](vela_completion.md)	 - Output shell completion code for the specified shell (bash or zsh)
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_config.md

@@ -1,10 +1,10 @@
 ## vela config
 
-Manage application configurations
+Manage configurations
 
 ### Synopsis
 
-Manage application configurations under given env
+Manage configurations
 
 ### Options
 
@@ -26,4 +26,4 @@ Manage application configurations under given env
 * [vela config ls](vela_config_ls.md)	 - List configs
 * [vela config set](vela_config_set.md)	 - Set data for a config
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_config_del.md

@@ -30,6 +30,6 @@ vela config del <config-name>
 
 ### SEE ALSO
 
-* [vela config](vela_config.md)	 - Manage application configurations
+* [vela config](vela_config.md)	 - Manage configurations
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_config_get.md

@@ -30,6 +30,6 @@ vela config get <config-name>
 
 ### SEE ALSO
 
-* [vela config](vela_config.md)	 - Manage application configurations
+* [vela config](vela_config.md)	 - Manage configurations
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_config_ls.md

@@ -30,6 +30,6 @@ vela config ls
 
 ### SEE ALSO
 
-* [vela config](vela_config.md)	 - Manage application configurations
+* [vela config](vela_config.md)	 - Manage configurations
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_config_set.md

@@ -30,6 +30,6 @@ vela config set <config-name> KEY=VALUE K2=V2
 
 ### SEE ALSO
 
-* [vela config](vela_config.md)	 - Manage application configurations
+* [vela config](vela_config.md)	 - Manage configurations
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_dashboard.md

@@ -38,4 +38,4 @@ dashboard
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_delete.md

@@ -1,13 +1,13 @@
 ## vela delete
 
-Delete Applications
+Delete an application
 
 ### Synopsis
 
-Delete Applications
+Delete an application
 
 ```
-vela delete <APPLICATION_NAME>
+vela delete APP_NAME
 ```
 
 ### Examples
@@ -33,4 +33,4 @@ vela delete frontend
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_env.md

@@ -1,10 +1,10 @@
 ## vela env
 
-Manage application environments
+Manage environments
 
 ### Synopsis
 
-Manage application environments
+Manage environments
 
 ### Options
 
@@ -26,4 +26,4 @@ Manage application environments
 * [vela env ls](vela_env_ls.md)	 - List environments
 * [vela env set](vela_env_set.md)	 - Set an environment
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_env_delete.md

@@ -30,6 +30,6 @@ vela env delete test
 
 ### SEE ALSO
 
-* [vela env](vela_env.md)	 - Manage application environments
+* [vela env](vela_env.md)	 - Manage environments
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_env_init.md

@@ -34,6 +34,6 @@ vela env init test --namespace test --email my@email.com
 
 ### SEE ALSO
 
-* [vela env](vela_env.md)	 - Manage application environments
+* [vela env](vela_env.md)	 - Manage environments
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_env_ls.md

@@ -30,6 +30,6 @@ vela env ls [env-name]
 
 ### SEE ALSO
 
-* [vela env](vela_env.md)	 - Manage application environments
+* [vela env](vela_env.md)	 - Manage environments
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_env_set.md

@@ -30,6 +30,6 @@ vela env set test
 
 ### SEE ALSO
 
-* [vela env](vela_env.md)	 - Manage application environments
+* [vela env](vela_env.md)	 - Manage environments
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_exec.md

@@ -1,13 +1,13 @@
 ## vela exec
 
-Execute a command in a container
+Execute command in a container
 
 ### Synopsis
 
-Execute a command in the 1st container of specific Application => Service => (1st)Pod
+Execute command in a container
 
 ```
-vela exec [flags] AppName -- COMMAND [args...]
+vela exec [flags] APP_NAME -- COMMAND [args...]
 ```
 
 ### Options
@@ -29,4 +29,4 @@ vela exec [flags] AppName -- COMMAND [args...]
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_init.md

@@ -1,10 +1,10 @@
 ## vela init
 
-Init an OAM Application
+Create scaffold for an application
 
 ### Synopsis
 
-Init an OAM Application by one command
+Create scaffold for an application
 
 ```
 vela init
@@ -33,4 +33,4 @@ vela init
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_install.md

@@ -1,10 +1,10 @@
 ## vela install
 
-Initialize vela on both client and server
+Install Vela Core with built-in capabilities
 
 ### Synopsis
 
-Install OAM runtime and vela builtin capabilities.
+Install Vela Core with built-in capabilities
 
 ```
 vela install [flags]
@@ -18,7 +18,7 @@ vela install [flags]
       --image-repo string          vela core image repo, this will align to chart value image.repo (default "oamdev/vela-core")
       --image-tag string           vela core image repo, this will align to chart value image.tag (default "latest")
   -p, --vela-chart-path string     path to vela core chart to override default chart
-  -w, --wait                       wait until vela-core is ready to serve
+  -w, --wait string                wait until vela-core is ready to serve, default will not wait (default "0s")
 ```
 
 ### Options inherited from parent commands
@@ -31,4 +31,4 @@ vela install [flags]
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_logs.md

@@ -27,4 +27,4 @@ vela logs [flags]
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_ls.md

@@ -4,7 +4,7 @@ List services
 
 ### Synopsis
 
-List services with their application, type, traits, status and created time, etc.
+List services of all applications
 
 ```
 vela ls
@@ -33,4 +33,4 @@ vela ls
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_metrics.md

@@ -1,19 +1,19 @@
-## vela metric
+## vela metrics
 
-Attach metric trait to an app
+Attach metrics trait to an app
 
 ### Synopsis
 
-Attach metric trait to an app
+Attach metrics trait to an app
 
 ```
-vela metric <appname> [args]
+vela metrics <appname> [args]
 ```
 
 ### Examples
 
 ```
-vela metric frontend
+vela metrics frontend
 ```
 
 ### Options
@@ -22,8 +22,8 @@ vela metric frontend
       --detach          detach trait from service
       --enabled          (default true)
   -f, --format string   format of the metrics, default as prometheus (default "prometheus")
-  -h, --help            help for metric
-      --path string      the metric path of the service (default "/metrics")
+  -h, --help            help for metrics
+      --path string      the metrics path of the service (default "/metrics")
       --port int         the port for metrics, will discovery automatically by default
       --scheme string    (default "http")
   -s, --staging         only save changes locally without real update application
@@ -40,4 +40,4 @@ vela metric frontend
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_port-forward.md

@@ -1,10 +1,10 @@
 ## vela port-forward
 
-Forward one or more local ports to a Pod of a service in an application
+Forward local ports to services in an application
 
 ### Synopsis
 
-Forward one or more local ports to a Pod of a service in an application
+Forward local ports to services in an application
 
 ```
 vela port-forward APP_NAME [options] [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]
@@ -16,6 +16,7 @@ vela port-forward APP_NAME [options] [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:
       --address strings                Addresses to listen on (comma separated). Only accepts IP addresses or localhost as a value. When localhost is supplied, vela will try to bind on both 127.0.0.1 and ::1 and will fail if neither of these addresses are available to bind. (default [localhost])
   -h, --help                           help for port-forward
       --pod-running-timeout duration   The length of time (like 5s, 2m, or 3h, higher than zero) to wait until at least one pod is running (default 1m0s)
+      --route                          forward ports from route trait service
 ```
 
 ### Options inherited from parent commands
@@ -28,4 +29,4 @@ vela port-forward APP_NAME [options] [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_rollout.md

@@ -22,9 +22,9 @@ vela rollout frontend
       --detach            detach trait from service
   -h, --help              help for rollout
       --interval string    (default "30s")
-      --replica int       total replica of the workload (default 5)
+      --replicas int      total replicas of the workload (default 2)
   -s, --staging           only save changes locally without real update application
-      --step-weight int   weight percent of every step in rolling update (default 20)
+      --step-weight int   weight percent of every step in rolling update (default 50)
       --svc string        specify one service belonging to the application
 ```
 
@@ -38,4 +38,4 @@ vela rollout frontend
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_route.md

@@ -37,4 +37,4 @@ vela route frontend
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_scaler.md

@@ -19,11 +19,11 @@ vela scaler frontend
 ### Options
 
 ```
-      --detach        detach trait from service
-  -h, --help          help for scaler
-  -r, --replica int    (default 1)
-  -s, --staging       only save changes locally without real update application
-      --svc string    specify one service belonging to the application
+      --detach         detach trait from service
+  -h, --help           help for scaler
+  -r, --replicas int    (default 1)
+  -s, --staging        only save changes locally without real update application
+      --svc string     specify one service belonging to the application
 ```
 
 ### Options inherited from parent commands
@@ -36,4 +36,4 @@ vela scaler frontend
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_show.md

@@ -1,19 +1,19 @@
 ## vela show
 
-Get details of an application
+Show details of an application
 
 ### Synopsis
 
-Get details of an application
+Show details of an application
 
 ```
-vela show <APPLICATION-NAME> [flags]
+vela show APP_NAME [flags]
 ```
 
 ### Examples
 
 ```
-vela show <APPLICATION-NAME>
+vela show APP_NAME
 ```
 
 ### Options
@@ -33,4 +33,4 @@ vela show <APPLICATION-NAME>
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_status.md

@@ -1,19 +1,19 @@
 ## vela status
 
-get status of an application
+Show status of an application
 
 ### Synopsis
 
-get status of an application, including workloads and traits of each service.
+Show status of an application, including workloads and traits of each service.
 
 ```
-vela status <APPLICATION-NAME> [flags]
+vela status APP_NAME [flags]
 ```
 
 ### Examples
 
 ```
-vela status <APPLICATION-NAME>
+vela status APP_NAME
 ```
 
 ### Options
@@ -33,4 +33,4 @@ vela status <APPLICATION-NAME>
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_svc.md

@@ -24,4 +24,4 @@ Manage services
 * [vela](vela.md)	 - 
 * [vela svc deploy](vela_svc_deploy.md)	 - Initialize and run a service
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_svc_deploy.md

@@ -35,4 +35,4 @@ vela svc deploy -t <SERVICE_TYPE>
 
 * [vela svc](vela_svc.md)	 - Manage services
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_system.md

@@ -23,4 +23,4 @@ System management utilities
 * [vela](vela.md)	 - 
 * [vela system info](vela_system_info.md)	 - Show vela client and cluster chartPath
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_system_info.md

@@ -26,4 +26,4 @@ vela system info [flags]
 
 * [vela system](vela_system.md)	 - System management utilities
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_template.md

@@ -23,4 +23,4 @@ Manage templates
 * [vela](vela.md)	 - 
 * [vela template context](vela_template_context.md)	 - Show context parameters
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_template_context.md

@@ -32,4 +32,4 @@ vela template context
 
 * [vela template](vela_template.md)	 - Manage templates
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_traits.md

@@ -7,7 +7,7 @@ List traits
 List traits
 
 ```
-vela traits [--apply-to WORKLOADNAME]
+vela traits [--apply-to WORKLOAD_NAME]
 ```
 
 ### Examples
@@ -34,4 +34,4 @@ vela traits
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_up.md

@@ -4,7 +4,7 @@ Apply an appfile
 
 ### Synopsis
 
-Apply an appfile, by default vela.yaml
+Apply an appfile
 
 ```
 vela up
@@ -27,4 +27,4 @@ vela up
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_version.md

@@ -26,4 +26,4 @@ vela version [flags]
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/cli/vela_workloads.md

@@ -33,4 +33,4 @@ vela workloads
 
 * [vela](vela.md)	 - 
 
-###### Auto generated by spf13/cobra on 10-Nov-2020
+###### Auto generated by spf13/cobra on 16-Nov-2020

docs/en/concepts.md

@@ -22,7 +22,7 @@ A service represents the runtime configurations (i.e., workload type and traits)
 ## Application
 An application in KubeVela is a collection of services which describes what a developer tries to build and ship from high level. An example could be an "website" application which is composed of two services "frontend" and "backend", or a "wordpress" application which is composed of "php-server" and "database".
 
-An application is defined by an `Appfile` (named `vela.yaml` by default) in KubeVela.
+An application is defined by an `Appfile` (named `vela.yaml` by default) in KubeVela. Please check its full schema in the [Appfile reference documentation](developers/references/devex/appfile.md).
 
 ## Environment
 Before releasing an application to production, it's important to test the code in testing/staging workspaces. In KubeVela, we describe these workspaces as "deployment environments" or "environments" for short. Each environment has its own configuration (e.g., domain, Kubernetes namespace, configuration data, access control policy etc.) to allow user to create different deployment environments such as "test" and "production".

docs/en/design.md

@@ -1,72 +1,71 @@
 # KubeVela Design
 
-This document is the detailed design and architecture of the KubeVela being built in this repository.
+This document presents the detailed design and architecture of KubeVela.
 
-> All the diagram in this documentation could be found in [this slides](https://docs.google.com/presentation/d/1Y3gnKrd7fUZGgee7Ia9vBsRIYhcZLQwMUCDkk1RJvQc).
+> All the diagrams in this document are available in [this slides](https://docs.google.com/presentation/d/1Y3gnKrd7fUZGgee7Ia9vBsRIYhcZLQwMUCDkk1RJvQc).
 
 ## User Stories
 
-As a end user (e.g. application developers, operators etc) of the platform, I only want to focus on coding my business logic and ship them to various environments at ease. Let's say:
+As an end user (e.g., application developer or operator) of a platform, I want to focus on implementing my business logic and ship the product to different environments at ease. In other words, my interactions with the platform should be as simple as:
 - Here's my source code.
-- Here's my application configuration (described in end user PoV).
-- Deploy it in test environment.
-- Deploy it in production environment.
+- Here's my application configuration (described from the end user perspective).
+- Deploy it in the test environment.
+- Deploy it in the production environment.
 - Monitoring, debugging, rollout/rollback the application.
-- Dockerfile is fine, but please keep it simple. 
+- Requiring dockerfile is fine, but please keep the format simple.
 
-As a platform engineer, I want to build a easy-to-use platform for end users. In detail, the platform should be:
-- Heroku-like (_in terms of both user experience and functionality_). 
-  - and I prefer to build my own version with OSS tools, particularly, with Kubernetes (for obvious reason).
-- Easy to build. 
-  -  I am too busy to reinvent any wheel, I want to reuse existing capabilities in Kubernetes community as features of my platform with minimal effort. Writing some simple CRD and controllers is fine, but please, just the simple ones.
+As a platform engineer, I want to build an easy-to-use platform for end users. In details, the platform should be:
+- Heroku-like (_in terms of both user experience and functionality_).
+  - I prefer to building my own version with OSS tools, particularly, with Kubernetes.
+- Easy to build.
+  - I want to reuse existing capabilities in the Kubernetes community with minimal efforts. Building the platform should be as simple as adding some simple CRD and controllers.
 - Powerful and highly extensible.
-  - I don't want to lock users with restricted abstractions and capabilities like traditional PaaS or FaaS/Serverless. I love Kubernetes and what it has enabled. So in terms of capability, I hope my platform is fully open and has unlimited possibilities like Kubernetes itself, rather than another opinionated close system like traditional PaaS.
+  - I don't want to lock users with restricted abstractions and capabilities like traditional PaaS or FaaS/Serverless. Hence in terms of capabilities, I hope my platform is fully open and has unlimited possibilities like Kubernetes, rather than another opinionated close system.
 
-## Core Principles
+## Design Principles
 
-For developers, KubeVela provides a out-of-the-box PaaS-ish experience that enables better productivity (i.e. focus, self-service, on-demand, and fast-feedback).
+For developers, KubeVela provides an out-of-the-box PaaS-ish experience that exhibits four characteristics: focus, self-service, on-demand, and fast-feedback.
 
-For platform builders, KubeVela works like a special Kubernetes "distro" or extensible PaaS core that could be used to build something more complex on top of. It enables platform builders to integrate existing capabilities in Kubernetes ecosystem with minimal effort, and/or develop a new capability at ease in a standard, Kubernetes-native approach.
+For platform builders, KubeVela works like a special Kubernetes "distro" or an extensible PaaS core. It enables platform builders to integrate existing capabilities in the Kubernetes ecosystems with minimal efforts, and/or develop a new capability in a standard, Kubernetes-native approach.
 
-## Design Details
+To achieve the above, Kubevela attempts to meet the following criteria.
 
-### 1. Application Centric
+## Criteria
+
+### Application Centric
 
 Keywords: _focus_, _self-service_.
 
-KubeVela intends to ensure developers only think in the scope of _application_, not container or infrastructure. We've seen lacking application context impacts the developer experience and raises the bar to adopt cloud native technology and we believe _application_ is the natural mindset for developers and it's the core API KubeVela should expose.
+KubeVela ensures developers to only think in the scope of an _application_, not a container or an infrastructure. We've seen that lacking application abstraction impacts the developer experience and raises the bar to adopt cloud native technologies. We believe _application_ is the most natural mindset for developers.
 
 ![alt](../resources/app-centric.png)
 
-In KubeVela, it is only push code, deploy application in developer facing primitives, and claim operations policies that developers would do. Thus, KubeVela choose to:
+Thus, KubeVela chooses to:
 1. Introduce _application_ as its first class API.
-2. Build the whole system around "application", i.e. model capabilities of Kubernetes as application configuration, with clarity and manageability.
+2. Build the whole system around "application" by modeling Kubernetes capabilities as application configuration in a clear and manageable manner.
 
 #### Solution
 
-One common solution to introduce such concept of "application" to Kubernetes is creating an "application CRD". However, as an extensible PaaS core, KubeVela intends to support any application type and any operation feature in Kubernetes ecosystem, thus instead of creating a in-house and "monolithic" CRD, KubeVela adopts [Open Application Model (OAM)](https://github.com/oam-dev/spec) as its application definition. This is empowers KubeVela with high extensibility since every workload and operation feature in OAM is modeled by independent definition object with full freedom to extend. Besides, the model in OAM is also well-defined as it defines micro-services application by default, and models operation features as part of the application (i.e. `Traits`).
+One common solution to model "application" in Kubernetes is creating an "application CRD". However, as an extensible PaaS core, KubeVela targets to support any application types and any operation features in the Kubernetes ecosystems. Hence instead of creating an in-house and "monolithic" CRD, KubeVela adopts [Open Application Model (OAM)](https://github.com/oam-dev/spec) as its application definition. This empowers KubeVela with high extensibility since every workload and operation feature in OAM is modeled by independent and extensible definition. OAM defines service application by default, and the operation features are modeled as extra configurations for the application.
 
-### 2. Capability Oriented Architecture
+### Capability Oriented
 
 Keywords: _on-demand_.
 
-Every capability in KubeVela is designed as a standalone "plug-in" in terms of implementation and configuration. This enables the extensibility of the platform, and gives platform builders full freedom to extend KubeVela into anything else they want (e.g. database PaaS, AI PaaS, etc.).
+Every capability in KubeVela is designed as a standalone "plug-in" in terms of implementation and configuration. This gives platform builders full flexibility to turn KubeVela into any platform they want (e.g., database PaaS, AI PaaS, etc.).
 
 ![alt](../resources/coa.png)
 
-This loosely coupled design adopts the idea of Capability Oriented Architecture (COA), i.e. instead of creating a close system like traditional PaaS, KubeVela intends to become an application-centric framework that could connect developers with any underlying infrastructure capability per demand.
+This loosely coupled design adopts the idea of Capability Oriented Architecture (COA), i.e., instead of creating a close system, KubeVela targets to become an application-centric framework that could expose any underlying infrastructure capability to developers on demand.
 
 #### Solution
 
-KubeVela core is built with [OAM Kubernetes Runtime](https://github.com/crossplane/oam-kubernetes-runtime) which met the requirements of KubeVela such as supporting bring in standalone controllers as workload type and trait. A set of abstraction and interfaces are defined in this library for KubeVela to assemble various Kubernetes capabilities into a platform without coupling them together or introducing any glue code.  
+KubeVela core is built based on [OAM Kubernetes Runtime](https://github.com/crossplane/oam-kubernetes-runtime) which supports adding standalone controllers as workload type or trait. A set of abstractions and interfaces are defined in this library for KubeVela to assemble various Kubernetes capabilities into a platform with minimal efforts.
 
-For example, there are several "built-in" workload types in KubeVela such as `Web Service` or `Task`. In implementation, KubeVela discovers them with OAM definition object, it does **NOT** need to be aware of the specification or implementation of these workload types, i.e. they could be Kubernetes built-in resources, or CRD controllers.
+For example, there are several "built-in" workload types in KubeVela such as `Web Service` or `Task`. KubeVela discovers them from OAM definition objects, it does **NOT** need to be aware of the specification or the implementation of these workload types regardless they are built-in resources, or CRDs. This means platform builders are free to introduce their own workload types by simply installing a CRD, or just referring to another k8s built-in resource such as `StatefulSet`.
 
-This means platform builders are free to bring their own workload types by simply install another CRD controller, or just reference another k8s built-in resource like StatefulSet as new workload type.
-
-Similarly, all the operation features such as `scaling` or `rollout` (i.e. "traits" in KubeVela) are independent from workload implementations. In KubeVela, traits will attempt to understand how to interact with a workload instance following [its characteristic labels](https://github.com/oam-dev/spec/blob/master/4.workload_definitions.md#labels) instead of coupling with specific implementation of workload. This enables platform builders to bring their own traits freely by simply providing another CRD controller, or reference another k8s built-in resource like `HPA` or `NetworkPolicy`.
-
-##### Capability Register and Discovery
+Similarly, all the operation features such as `scaling` or `rollout` (i.e. "traits" in KubeVela) are not tied to particular implementations. In KubeVela, traits are assigned to
+a workload type instance following the instance's [characteristic labels](https://github.com/oam-dev/spec/blob/master/4.workload_definitions.md#labels). This enables platform builders to freely add their own traits by simply installing a CRD, or referring to another k8s built-in resource such as `HPA` or `NetworkPolicy`.
 
 KubeVela leverages [OAM definition objects](https://github.com/oam-dev/spec/blob/master/4.workload_definitions.md) to register and discover workloads and traits:
 
@@ -76,41 +75,30 @@ $ kubectl apply -f workload-definition.yaml # register a new workload type
 $ kubectl apply -f trait-definition.yaml # register a new trait
 ```
 
-Note that OAM definition objects only care about API resource, not including the controllers. Thus KubeVela intends to include a **CRD registry** so whenever a new API resource is installed as workload or trait, KubeVela could install its controller automatically from the registry. That of course means we envision the CRD registry could register a CRD and Helm chart (which contains the manifest of the controller). In practice, we are currently evaluating RedHat's Operator Lifecycle Manager (OLM) but no the final conclusion yet.
+Note that the OAM definition objects only define the APIs, not including the controllers. Thus KubeVela provides a **CRD registry** so whenever a new CRD is installed as a workload or a trait, KubeVela would install its controller automatically from the registry. The CRD registry could register a CRD and the Helm chart (which contains the manifest of the controller) together. In fact, we are currently evaluating RedHat's Operator Lifecycle Manager (OLM) capability discovery but have not drawn the final conclusion yet.
 
-##### Cloud Services Integration
+For capabilities provided by cloud services, KubeVela will leverage [Crossplane](https://github.com/crossplane/crossplane) core to register and provision them as OAM workload types or traits.
 
-For capabilities like cloud services, KubeVela intends to leverage [Crossplane](https://github.com/crossplane/crossplane) core to register and provision cloud services as OAM workload types.
 
-### 3. Extensible User Interface
+### Extensible User Interface
 
 Keywords: _self-service_, _on-demand_, _fast-feedback_
 
-So far, **ALL** functionalities of KubeVela core can be handled by simple `kubectl`, for example:
+In the server side, KubeVela components are essentially the [Control Plane Objects](https://github.com/oam-dev/spec/blob/master/2.overview_and_terminology.md#control-plane-objects) defined in OAM specification. On top of those, KubeVela creates a lightweight user facing layer with the following goals:
 
-```yaml
-$ kubectl apply -f frontend-component.yaml # create frontend component
-$ kubectl apply -f backend-component.yaml # create backend component
-$ kubectl apply -f application-config.yaml # assign operational traits to components and deploy the whole application
-```
-
-We call these server side API resources "the model objects" of KubeVela. They are essentially the [Control Plane Objects](https://github.com/oam-dev/spec/blob/master/2.overview_and_terminology.md#control-plane-objects) defined in OAM specification.
-
-On the other hand, KubeVela intend to create a lightweight user facing layer on the top of the model objects, with following goals in mind:
-
-- Shorten the learning curve of new developers. Most capabilities in Kubernetes are developed by big
-companies that run very complex workloads. However, for the bigger developer community, the new user facing layer will provide a much simpler path to on-board these capabilities.
-- Developers can describe their applications and behavior of their components without making assumptions on availability of specific Kubernetes API. For instance, a developer will be able to model auto-scaling needs without referring to the CRD of auto-scaling trait.
-- Provides a single source of truth of the application description. The user facing layer allows developers to work with a single artifact to capture the application definition. This artifact is the definitive truth of how the application is supposed to look like. It simplifies administrative tasks such as change management. It also serves as an anchor for application truth to avoid configuration drifts during operation.
-- Highly extensible. For example, when a new workload type or trait is installed, the end users could access this new capability directly from user interface layer, no re-compile or re-deploy of KubeVela is required.
+- Lower the learning curve of new developers. Most of the capabilities in Kubernetes are developed by
+companies that run complex workloads. The Kubevela user facing layer provides a much simpler path for on-boarding these capabilities.
+- Developers can describe their applications and the behaviors of their components without relying on Kubernetes APIs. For instance, a developer will be able to model the auto-scaling requirements without referring to the underline auto-scaler CRD.
+- Provide a single source of truth of the application description. The user facing layer allows developers to work with a single artifact to capture the application definition. It simplifies administrative tasks and also serves as an anchor to avoid configuration drifts during operation.
+- To be highly extensible. For example, when a new workload type or trait is installed, the end users could access this new capability directly from the user interface layer, no recompilation or redeployment of KubeVela is required.
 
 #### Solution
 
-In KubeVela, we introduced a docker-compose style "appfile" with higher level abstractions as the main user interface of the platform, so developers can define and deploy an application with a single command: `$ vela up`.
+In KubeVela, we introduced a docker-compose style "appfile" with high level abstractions as the main user interface of the platform. Developers can define and deploy an application with a single command: `$ vela up`.
 
-Plus, the schema of `appfile` is designed to be "assembled" with independent workload type and traits defined with OAM specification. For example:
+In addition, the schema of `appfile` is designed to be "assembled" with independent workload types and traits defined using OAM specification. For example:
 
-```
+```yaml
 services:
   frontend:
     type: webservice
@@ -122,34 +110,27 @@ services:
         "/": 8080
  ```
 
-This `appfile` is composed by a `frontend` component with workload type of `Web Service` and a `route` trait. Developer fill in the values based on indepedent schema documentations for such workload type and trait, and KubeVela will check corresponding definitions objects in OAM Kubernetes implementation to validate and generate the final Kubernetes resources. This is how we make the user interface of KubeVela highly extensible.
+This `appfile` is composed of a `frontend` component including workload type of `Web Service` and a `route` trait. Developer fills in the values based on the independent schema documentations for such workload type and trait. KubeVela will check the corresponding definition objects in OAM Kubernetes runtime to validate and generate the final Kubernetes resources. This is how we make the user interface of KubeVela highly extensible.
 
-Besides, in order to make building higher level abstractions easier, we adopted [CUElang](https://github.com/cuelang/cue) in the implementation of OAM on Kubernetes, especially, for creating last mile abstractions (i.e eliminate non user facing fields or compose multiple objects into one). This makes all the abstractions in `appfile` essentially defined by CUE templates in OAM Control Plane Objects and the platform builders are free to modify those template at any time. This update will take effect immediately in the schema of `appfile`.
+In order to make building such high level abstractions easier, we adopted [CUElang](https://github.com/cuelang/cue) in the OAM Kubernetes runtime for creating the "last mile" abstractions (i.e., eliminating non user facing fields or merging multiple objects into one). All the abstractions in `appfile` are essentially defined by the CUE templates saved in the OAM Control Plane Objects. The platform builders can modify those templates at any time. The updates will take effect immediately in the schema of the `appfile`.
 
 ![alt](../resources/appfile.png)
 
-> In OAM community, `appfile` is the experimental effort to introduce _User Facing Objects_ alongside with the existing _Control Plane Objects_ in OAM specification. Feel free to check its [design doc](https://github.com/oam-dev/kubevela/blob/master/docs/design/appfile-design.md) for more detail.
+> In the OAM community, `appfile` is an experimental effort to introduce _User Facing Objects_ alongside with the existing _Control Plane Objects_ in OAM specification. Feel free to check its [design doc](./design/appfile-design.md) for more details.
 
-KubeVela also introduced a command line to which can generate `appfile` in easy approach. For example, the command below will generate and deploy the above `frontend` service to KubeVela directly:
-
-```bash
-$ vela svc deploy frontend -t webservice --image oamdev/testapp:v1
-```
-
-Similarly, the dashboard of KubeVela is essentially a GUI version of `appfile` where the schema of forms are also highly extensible based on the mechanism above.
+KubeVela provides a command line to generate `appfile` easily. The dashboard of KubeVela is essentially a GUI version of `appfile`.
 
 ## Architecture
 
+Overall, as illustrated in the following figure, KubeVela is composed of **two components**:
 ![alt](../resources/arch.png)
 
-From highest level, KubeVela is composed by only **two components**:
-
 ### KubeVela User Interfaces
-User interfaces of KubeVela, including: `appfile`, `cli` and `dashboard`.
+The main user interface of KubeVela is `appfile` (i.e. `Application`), with `cli` and `dashboard` build around this concept.
 
 ### KubeVela Core
-KubeVela core is a server side controller which is composed by:
-- [Crossplane OAM Kubernetes runtime](https://github.com/crossplane/oam-kubernetes-runtime) to provide Control Plane Objects such as `Component` and `Application Configuration` etc.
-- Built-in workload and trait implementations to provide core capabilities such as `webservice`, `route` and `rollout` etc.
-- Capability Management: manage features (i.e. workload types and traits) of KubeVela as independent add-ons following the design of _Capability Oriented Architecture_ mentioned above.
-- CRD Registry: register and discover Kubernetes controllers by its CRD. This enables KubeVela automatically install dependent controllers/operators triggered by "CRD missing" event when any new workload type or trait is added.
+It is a server side controller which is composed of:
+- [Crossplane OAM Kubernetes runtime](https://github.com/crossplane/oam-kubernetes-runtime) which implements OAM control plane specification including `Component` and `Application Configuration` etc.
+- Built-in workload and trait implementations which provide core capabilities such as `webservice`, `route` and `rollout` etc.
+- A capability manager which manages features of KubeVela as independent add-ons following the design of _Capability Oriented Architecture_ mentioned above.
+- A CRD registry which registers and discovers Kubernetes controllers/operators by their CRDs. This enables KubeVela to install dependent controllers/operators automatically when a new CRD based capability is added.

docs/en/developers/alternative-cmd.md

@@ -0,0 +1,307 @@
+# Alternative Commands
+
+Besides Appfile, KubeVela also provides a set of alternatives commands to deploy the application. Think about "shortcuts" that could generate and apply Appfile without the need to write YAML file manually.
+
+> NOTE: These shortcuts are based on Appfile and designed for quick demo purpose only, we would recommend using Appfile instead for serious usage of KubeVela.
+
+## `vela init`
+
+A shortcut to initialize and deploy an application with one service, run:
+
+> If you only want to initialize the Appfile only (i.e. dry run), add `--render-only` flag
+
+```bash
+$ vela init
+Welcome to use KubeVela CLI! We're going to help you run applications through a couple of questions.
+
+Environment: default, namespace: default
+
+? What is the domain of your application service (optional):  example.com
+? What is your email (optional, used to generate certification):
+? What would you like to name your application (required):  testapp
+? Choose the workload type for your application (required, e.g., webservice):  webservice
+? What would you like to name this webservice (required):  testsvc
+? Which image would you like to use for your service (required): crccheck/hello-world
+? Which port do you want customer traffic sent to (optional, default is 80): 8000
+
+...
+✅ Application Deployed Successfully!
+  - Name: testsvc
+    Type: webservice
+    HEALTHY Ready: 1/1
+    Routes:
+
+    Last Deployment:
+      Created at: ...
+      Updated at: ...
+```
+
+Check the application:
+
+```bash
+$ vela show testapp
+About:
+
+  Name:      	testapp
+  Created at:	...
+  Updated at:	...
+
+
+Environment:
+
+  Namespace:	default
+
+Services:
+
+  - Name:        	testsvc
+    WorkloadType:	webservice
+    Arguments:
+      image:        	crccheck/hello-world
+      port:         	8000
+      Traits:
+```
+
+## `vela svc deploy`
+
+A shortcut to initialize and deploy service one by one.
+
+Firstly, check the available workload types.
+
+```bash
+$ vela workloads
+NAME      	DESCRIPTION
+worker   	Backend worker without ports exposed
+webservice	Long running service with network routes
+```
+
+Deploy the first service named `frontend` with `Web Service` type:
+
+```bash
+$ vela svc deploy frontend --app testapp -t webservice --image crccheck/hello-world
+App testapp deployed
+```
+
+Deploy the second service named `backend` with "Backend Worker" type:
+
+```bash
+$ vela svc deploy backend --app testapp2 -t worker --image crccheck/hello-world
+App testapp2 deployed
+```
+
+```bash
+$ vela ls
+SERVICE 	APP     	TYPE	TRAITS	STATUS 	CREATED-TIME
+frontend	testapp 	    	      	...
+backend 	testapp 	    	      	...
+```
+
+## `vela route`
+
+A shortcut to add route config.
+
+```bash
+$ vela route testapp --domain frontend.mycustom.domain
+Adding route for app frontend
+
+Rendering configs for service (frontend)...
+⠋ Deploying ...
+✅ Application Deployed Successfully!
+Showing status of service(type: webservice) frontend deployed in Environment myenv
+Service frontend Status:   HEALTHY Ready: 1/1
+  route:  Visiting URL: http://frontend.mycustom.domain IP: 123.57.10.233
+
+Last Deployment:
+  Created at: 2020-10-29 15:45:13 +0800 CST
+  Updated at: 2020-10-29T16:12:45+08:00
+```
+
+Then you will be able to visit by:
+
+```shell script
+$ curl -H "Host:frontend.mycustom.domain" 123.57.10.233
+```
+
+If you have domain set in deployment environment
+
+```bash
+$ vela route testapp
+Adding route for app frontend
+
+Rendering configs for service (frontend)...
+⠋ Deploying ...
+✅ Application Deployed Successfully!
+Showing status of service(type: webservice) frontend deployed in Environment default
+Service frontend Status:   HEALTHY Ready: 1/1
+  route:  Visiting URL: https://frontend.123.57.10.233.xip.io IP: 123.57.10.233
+
+Last Deployment:
+  Created at: 2020-10-29 11:26:46 +0800 CST
+  Updated at: 2020-10-29T11:28:01+08:00
+```
+
+## `vela autoscale`
+
+A shortcut to autoscale the service.
+Currently, Cli only supports setting CPU resource utilization auto-scaling policy. To configure cron auto-scaling policy,
+please refer to [autoscale in Appfile](/en/developers/set-autoscale.md).
+
+- Deploy an application
+
+  Run the following command to deploy application `helloworld`.
+
+  ```
+  $ vela svc deploy frontend -t webservice -a helloworld --image nginx:1.9.2 --port 80 --cpu=0.05
+  App helloworld deployed
+  ```
+
+  By default, the replicas of the workload webservice `helloworld` is one.
+
+- Scale the application by CPU utilization metrics
+  ```
+  $ vela autoscale helloworld --svc frontend --min 1 --max 5 --cpu-percent 5
+  Adding autoscale for app frontend
+  ⠋ Checking Status ...
+  ✅ Application Deployed Successfully!
+    - Name: frontend
+      Type: webservice
+      HEALTHY Ready: 1/1
+      Traits:
+        - ✅ autoscale: type: cpu     cpu-utilization(target/current): 5%/0%	replicas(min/max/current): 1/5/0
+      Last Deployment:
+        Created at: 2020-11-06 16:10:54 +0800 CST
+        Updated at: 2020-11-06T16:19:04+08:0
+  ```
+
+- Monitor the replicas changing when the application becomes overloaded
+
+  Continue to monitor the replicas changing when the application becoming overloaded. You can use Apache HTTP server
+  benchmarking tool `ab` to mock many requests to the application as we did in [Autoscalig in Appfile](/en/developers/set-autoscale.md).
+
+  With more and more requests to the application, the replicas gradually increase from one to four.
+
+## `vela metrics`
+
+A shortcut to add metrics config.
+
+If your application has exposed metrics, you can easily setup monitoring system
+with the help of `metrics` capability.
+
+Let's run [`christianhxc/gorandom:1.0`](https://github.com/christianhxc/prometheus-tutorial) as an example app.
+The app will emit random latencies as metrics.
+
+```bash
+$ vela svc deploy metricapp -t webservice --image christianhxc/gorandom:1.0 --port 8080
+```
+
+Then add metrics by:
+
+```bash
+$ vela metrics metricapp
+Adding metrics for app metricapp
+⠋ Deploying ...
+✅ Application Deployed Successfully!
+  - Name: metricapp
+    Type: webservice
+    HEALTHY Ready: 1/1
+    Routes:
+      - ✅ metrics: Monitoring port: 8080, path: /metrics, format: prometheus, schema: http.
+    Last Deployment:
+      Created at: 2020-11-02 14:31:56 +0800 CST
+      Updated at: 2020-11-02T14:32:00+08:00
+```
+
+The metrics trait will automatically discover port and label to monitor if no parameters specified.
+If more than one ports found, it will choose the first one by default.
+
+Verify that the metrics are collected on prometheus
+<details>
+
+```shell script
+$ kubectl --namespace monitoring port-forward `k -n monitoring get pods -l prometheus=oam -o name` 9090
+```
+
+Then access the prometheus dashboard via http://localhost:9090/targets
+
+</details>
+
+## `vela rollout`
+
+A shortcut to add rollout config.
+
+Firstly, deploy your app by:
+
+```shell script
+$ vela svc deploy testapp -t webservice --image oamdev/testapp:v1 --port 8080
+App testapp deployed
+```
+
+Add route for visit:
+
+```shell script
+$ vela route testapp --domain myhost.com
+Adding route for app testapp
+⠋ Checking Status ...
+✅ Application Deployed Successfully!
+  - Name: testapp
+    Type: webservice
+    HEALTHY Ready: 1/1
+    Traits:
+      - ✅ route:  Visiting URL: http://myhost.com IP: <your-ingress-IP-address>
+
+    Last Deployment:
+      Created at: 2020-11-09 12:50:30 +0800 CST
+      Updated at: 2020-11-09T12:51:19+08:00
+```
+
+```shell script
+$ curl -H "Host:myhost.com" http://<your-ingress-IP-address>/
+Hello World%
+```
+
+Secondly, add rollout policy for your app:
+
+```shell script
+$ vela rollout testapp --replicas 5 --step-weight 20 --interval 5s
+```
+
+Then update your app by:
+
+```shell script
+$ vela svc deploy testapp -t webservice --image oamdev/testapp:v2 --port 8080
+```
+
+Then it will rolling update your instance, you could try `curl` your app multiple times:
+
+```shell script
+$ curl -H "Host:myhost.com" http://39.97.232.19/
+Hello World  -- Updated Version Two!%                                         
+$ curl -H "Host:myhost.com" http://39.97.232.19/
+Hello World%                                                                  
+$ curl -H "Host:myhost.com" http://39.97.232.19/
+Hello World%                                                                  
+$ curl -H "Host:myhost.com" http://39.97.232.19/
+Hello World  -- Updated Version Two!%                                         
+$ curl -H "Host:myhost.com" http://39.97.232.19/
+Hello World%                                                                  
+$ curl -H "Host:myhost.com" http://39.97.232.19/
+Hello World  -- Updated Version Two!%
+``` 
+
+It will return both version of output info as both instances are all existing.
+
+<details>
+  <summary>Under the hood, it was flagger canary running.</summary>
+
+```shell script
+$ kubectl get canaries.flagger.app testapp-trait-76fc76fddc -w
+NAME                       STATUS        WEIGHT   LASTTRANSITIONTIME
+testapp-trait-76fc76fddc   Progressing   0        2020-11-10T09:06:10Z
+testapp-trait-76fc76fddc   Progressing   20       2020-11-10T09:06:30Z
+testapp-trait-76fc76fddc   Progressing   40       2020-11-10T09:06:40Z
+testapp-trait-76fc76fddc   Progressing   60       2020-11-10T09:07:31Z
+testapp-trait-76fc76fddc   Promoting     0        2020-11-10T09:08:00Z
+testapp-trait-76fc76fddc   Promoting     100      2020-11-10T09:08:10Z
+testapp-trait-76fc76fddc   Finalising    0        2020-11-10T09:08:20Z
+testapp-trait-76fc76fddc   Succeeded     0        2020-11-10T09:08:30Z
+```
+</details>

docs/en/developers/app-init.md

@@ -1,94 +0,0 @@
-# Initializating Application
-
-## `vela init`
-
-To initialize and deploy an application with one service, run:
-
-> If you only want to initialize without deploying the app, add `--render-only` flag
-
-```bash
-$ vela  init
-Welcome to use KubeVela CLI! We're going to help you run applications through a couple of questions.
-
-Environment: default, namespace: default
-
-? What is the domain of your application service (optional):  example.com
-? What is your email (optional, used to generate certification):
-? What would you like to name your application (required):  testapp
-? Choose the workload type for your application (required, e.g., webservice):  webservice
-? What would you like to name this webservice (required):  testsvc
-? specify app image crccheck/hello-world
-? specify port for container 8000
-
-...
-✅ Application Deployed Successfully!
-  - Name: testsvc
-    Type: webservice
-    HEALTHY Ready: 1/1
-    Routes:
-
-    Last Deployment:
-      Created at: ...
-      Updated at: ...
-```
-
-Check the application:
-
-```bash
-$ vela show testapp
-About:
-
-  Name:      	testapp
-  Created at:	...
-  Updated at:	...
-
-
-Environment:
-
-  Namespace:	default
-
-Services:
-
-  - Name:        	testsvc
-    WorkloadType:	webservice
-    Arguments:
-      image:        	crccheck/hello-world
-      port:         	8000
-      Traits:
-```
-
-## Deploy Multiple Services
-
-You can also use KubeVela CLI to deploy multiple services for an application.
-
-Check the available workload types.
-
-```bash
-$ vela workloads
-NAME      	DESCRIPTION
-worker   	Backend worker without ports exposed
-webservice	Long running service with network routes
-```
-
-Deploy the first service named `frontend` with `Web Service` type:
-
-```bash
-$ vela svc deploy frontend --app testapp -t webservice --image crccheck/hello-world
-App testapp deployed
-```
-
-> TODO auto generate a random application name, so --app testapp becomes optional
-
-Deploy the second service named `backend` with "Backend Worker" type:
-
-```bash
-$ vela svc deploy backend --app testapp2 -t worker --image crccheck/hello-world
-App testapp2 deployed
-```
-
-```bash
-$ vela ls
-SERVICE 	APP     	TYPE	TRAITS	STATUS 	CREATED-TIME
-frontend	testapp 	    	      	...
-backend 	testapp 	    	      	...
-```

docs/en/developers/cap-center.md

@@ -1,10 +1,12 @@
 # Managing Capabilities
 
-This tutorial talks about how to install capabilities (caps) from remote centers.
+In KubeVela, developers can install more capabilities (i.e. new workload types and traits) from any GitHub repo that contains OAM definition files. We call these GitHub repos as _Capability Centers_. 
 
-## Add Cap Center
+KubeVela is able to discover OAM definition files in this repo automatically and sync them to your own KubeVela platform.
 
-Add and sync a remote center:
+## Add a capability center
+
+Add and sync a capability center in KubeVela:
 
 ```bash
 $ vela cap center config my-center https://github.com/oam-dev/catalog/tree/master/registry
@@ -16,7 +18,11 @@ successfully sync 1/1 from my-center remote center
 sync finished
 ```
 
-## List Cap Centers
+Now, this capability center `my-center` is ready to use.
+
+## List capability centers
+
+You are allowed to add more capability centers and list them.
 
 ```bash
 $ vela cap center ls
@@ -24,13 +30,17 @@ NAME     	ADDRESS
 my-center	https://github.com/oam-dev/catalog/tree/master/registry
 ```
 
-## [Optional] Remove Cap Center
+## [Optional] Remove a capability center
+
+Or, remove one.
 
 ```bash
 $ vela cap center remove my-center
 ```
 
-## List Caps
+## List all available capabilities in capability center
+
+Or, list all available capabilities in certain center.
 
 ```bash
 $ vela cap ls my-center
@@ -38,7 +48,13 @@ NAME     	CENTER   	TYPE 	DEFINITION                  	STATUS     	APPLIES-TO
 kubewatch	my-center	trait	kubewatches.labs.bitnami.com	uninstalled	[]
 ```
 
-## Install Cap
+## Install a capability from capability center
+
+Now let's try to install the new trait named `kubewatch` from `my-center` to your own KubeVela platform.
+
+> [KubeWatch](https://github.com/bitnami-labs/kubewatch) is a Kubernetes plugin that watches events and publishes notifications to Slack channel etc. We can use it as a trait to watch important changes of your app and notify the platform administrators via Slack.
+
+Install `kubewatch` trait from `my-center`.
 
 ```bash
 $ vela cap install my-center/kubewatch
@@ -51,7 +67,10 @@ Successfully installed chart (kubewatch) with release name (kubewatch)
 Successfully installed capability kubewatch from my-center
 ```
 
-Check traits installed:
+## Use the newly installed capability
+
+Let's check the `kubewatch` trait appears in your platform firstly:
+
 ```bash
 $ vela traits
 Synchronizing capabilities from cluster⌛ ...
@@ -61,9 +80,50 @@ kubewatch 	trait   	Add a watch for resource
 ...
 ```
 
-## Uninstall Cap
+Great! Now let's deploy an app via Appfile.
 
-> Note: make sure no apps are using the capability before uninstalling.
+
+```bash
+$ cat << EOF > vela.yaml
+name: testapp
+services:
+  testsvc:
+    type: webservice
+    image: crccheck/hello-world
+    port: 8000
+    route:
+      domain: testsvc.example.com
+EOF
+```
+
+```bash
+$ vela up
+```
+
+Then let's add `kubewatch` as a trait in this Appfile.
+
+```bash
+$ cat << EOF >> vela.yaml
+    kubewatch:
+      webhook: https://hooks.slack.com/<your-token>
+EOF
+```
+
+> The `https://hooks.slack.com/<your-token>` is the Slack channel that your platform administrators are keeping an eye on.
+
+Update the deployment:
+
+```
+$ vela up
+```
+
+Now, your platform administrators should receive notifications whenever important changes happen to your app. For example, a fresh new deployment.
+
+![Image of Kubewatch](../../resources/kubewatch-notif.jpg)
+
+## Uninstall a capability
+
+> NOTE: make sure no apps are using the capability before uninstalling.
 
 ```bash
 $ vela cap uninstall my-center/kubewatch

docs/en/developers/cloud-service.md

@@ -1,68 +0,0 @@
-# Cloud service
-
-In this demo, we will add an RDS database from Alibaba Cloud to our application.
-
-## What is cloud service
-
-Cloud service refers to the managed cloud resources. For example, you can buy a PostgreSql database from a cloud vendor instead of setting up your own. Cloud service are normally outside of your Kubernetes cluster, but logically they are still part of your application. KubeVela provides application centric view of your applications. It will treat every service the same.
-
-## Crossplane
-
-Crossplane is an open source Kubernetes add-on that extends any cluster with the ability to provision and manage cloud infrastructure, services, and applications using kubectl, GitOps, or any tool that works with the Kubernetes API. The benefit of using Crossplane is it will provide centralized control plane disregard where your cluster is.
-
-KubeVela will delegate the lifecycle management of cloud service to Crossplane.
-
-## Install Crossplane (This demo uses crossplane version 0.13)
-
-You will need a Kubernetes cluster ver> 1.16 (Minikube and Kind clusters are fine).   
-Also you will need to have KubeVela installed on the cluster.   
-The folder that containes all the demo scripts are under [examples/kubecondemo/](https://github.com/oam-dev/kubevela.io/tree/master/examples/kubecondemo). For your convience, cd to that folder first:  
-`cd examples/kubecondemo/`
-To provision a cloud resource, you need to have the Access Key and Secret to your Alibaba cloud account.
-
-* Create crossplane namespace: `kubectl create ns crossplane-system`
-* Install crossplane helm chart: `helm install crossplane  charts/crossplane/ --namespace crossplane-system`
-* Install crossplane cli: `curl -sL https://raw.githubusercontent.com/crossplane/crossplane/release-0.13/install.sh | sh`
-* Add crossplane to `PATH`:  `sudo mv kubectl-crossplane /usr/local/bin`
-* Configure cloud provider(Alibaba Cloud) 
-  * Add cloud provider: `kubectl crossplane install provider crossplane/provider-alibaba:v0.3.0`
-  * Create provider secret: `kubectl create secret generic alibaba-creds --from-literal=accessKeyId=<change here> --from-literal=accessKeySecret=<change here> -n crossplane-system`
-  * Configure the provider: `kubectl apply -f script/provider.yaml`
-* Configure infrastructure: `kubectl crossplane install configuration crossplane/getting-started-with-alibaba:v0.13`
-
-So far we have configured Crossplane on the cluster.
-
-## Import the database workload definition
-
-First, register the db workload definition:   
-`kubectl apply -f script/def_db.yaml`   
-The webservice workload is different from the default version so we have to overwrite it.   
-`kubectl apply -f cript/webservice.yaml`   
-Don't forget to update vela:   
-`vela system update`   
-
-## Apply the appfile
-
-In the Appfile, we claim an RDS instance just like other services:
-
-``` yaml
-database:
-    type: rds
-    name: alibabaRds
-    ...
-```
-
-Next, we start the application:   
-`vela up`
-
-## Verify the database status
-
-Under the hood, we can verify the status of database(usually takes >6 min to be ready):   
-`kubectl get postgresqlinstance`
-
-When the database is ready, you can see the `READY: True` output.
-
-## Access the web-ui
-
-In the Appfile we added a route trait. To access the web-ui, please check out the [route](set-route.md) documentation.
-

docs/en/developers/config-enviroments.md

@@ -1,6 +1,6 @@
 # Setting Up Deployment Environment
 
-Before working with your application, you need to prepare a deployment environment (e.g. test, staging, prod etc) which will configure the workspace, email for certificate issuer and domain for your application.
+A deployment environment is where you could configure the workspace, email for certificate issuer and domain for your applications globally. A typical set of deployment environment is `test`, `staging`, `prod`, etc.
 
 ## Create environment
 
@@ -67,4 +67,24 @@ $ vela env init demo --domain 123.57.10.233.xip.io
 environment demo updated, Namespace: demo, Email: my@email.com
 ```
 
+### Using domain in Appfile
+
+Since you now have domain configured globally in deployment environment, you don't need to specify the domain in route configuration anymore.
+
+```yaml
+# in demo environment
+servcies:
+  express-server:
+    ...
+
+    route:
+      rules:
+        - path: /testapp
+          rewriteTarget: /
+```
+
+```
+$ curl http://123.57.10.233.xip.io/testapp
+Hello World
+```
 

docs/en/developers/devex/appfile.md

@@ -1,258 +0,0 @@
-# Using Appfile for More Flexible Configuration
-
-Appfile supports more flexible options than CLI/UI to configure appliation deployment on Vela.
-A detailed design doc could be found [here](https://github.com/oam-dev/kubevela/blob/master/docs/design/appfile-design.md).
-
-In this tutorial, we will build and deploy an example NodeJS app under [examples/testapp/](https://github.com/oam-dev/kubevela.io/tree/master/examples/testapp).
-
-## Prerequisites
-
-- [docker](https://docs.docker.com/get-docker/) installed on the host
-- [vela](../../install.md) installed and configured
-
-## 1. Download test app code
-
-git clone and go to the testapp directory:
-
-```bash
-$ git clone https://github.com/oam-dev/kubevela.io.git
-$ cd kubevela.io/examples/testapp
-```
-
-The example contains NodeJS app code, Dockerfile to build the app.
-
-## 2. Deploy app in one command
-
-In the directory there is a [vela.yaml](https://github.com/oam-dev/kubevela.io/tree/master/examples/testapp/vela.yaml) which follows Appfile format supported by Vela.
-We are going to use it to build and deploy the app.
-
-ATTENTION: change the image field in vela.yaml to something you can push to on your host:
-
-> Or you may try the local testing option introduced in the following section.
-
-```yaml
-    image: oamdev/testapp:v1
-```
-
-Run the following command:
-
-```bash
-$ vela up
-Parsing vela.yaml ...
-Loading templates ...
-
-Building service (express-server)...
-Sending build context to Docker daemon  71.68kB
-Step 1/10 : FROM mhart/alpine-node:12
- ---> 9d88359808c3
-...
-
-pushing image (oamdev/testapp:v1)...
-...
-
-Rendering configs for service (express-server)...
-Writing deploy config to (.vela/deploy.yaml)
-
-Applying deploy configs ...
-Checking if app has been deployed...
-App has not been deployed, creating a new deployment...
-✅ App has been deployed 🚀🚀🚀
-    Port forward: vela port-forward testapp
-             SSH: vela exec testapp
-         Logging: vela logs testapp
-      App status: vela status testapp
-  Service status: vela status testapp --svc express-server
-```
-
-
-Check the status of the service:
-
-```bash
-$ vela status testapp
-  About:
-  
-    Name:      	testapp
-    Namespace: 	default
-    Created at:	2020-11-02 11:08:32.138484 +0800 CST
-    Updated at:	2020-11-02 11:08:32.138485 +0800 CST
-  
-  Services:
-  
-    - Name: express-server
-      Type: webservice
-      HEALTHY Ready: 1/1
-      Last Deployment:
-        Created at: 2020-11-02 11:08:33 +0800 CST
-        Updated at: 2020-11-02T11:08:32+08:00
-      Routes:
-
-```
-
-### Alternative: Local testing without pushing image remotely
-
-If you have local [kind](../../install.md#kind) cluster running, you may try the local push option without pushing image remotely.
-
-Add local option to `build`:
-
-```yaml
-    build:
-      # push image into local kind cluster without remote transfer
-      push:
-        local: kind
-
-      docker:
-        file: Dockerfile
-        context: .
-```
-
-Then deploy the app to kind:
-
-```bash
-$ vela up
-```
-
-### [Optional] Check rendered manifests
-
-By default, Vela renders the final manifests in `.vela/deploy.yaml`:
-
-```yaml
-apiVersion: core.oam.dev/v1alpha2
-kind: ApplicationConfiguration
-metadata:
-  name: testapp
-  namespace: default
-spec:
-  components:
-  - componentName: express-server
----
-apiVersion: core.oam.dev/v1alpha2
-kind: Component
-metadata:
-  name: express-server
-  namespace: default
-spec:
-  workload:
-    apiVersion: apps/v1
-    kind: Deployment
-    metadata:
-      name: express-server
-    ...
----
-apiVersion: core.oam.dev/v1alpha2
-kind: HealthScope
-metadata:
-  name: testapp-default-health
-  namespace: default
-spec:
-  ...
-```
-
-## 3. Add routing
-
-Add routing config under `express-server`:
-
-```yaml
-servcies:
-  express-server:
-    ...
-
-    route:
-      domain: example.com
-      rules:
-        - path: /testapp
-          rewriteTarget: /
-```
-
-Apply again:
-
-```bash
-$ vela up
-```
-
-Check the status until we see route trait ready:
-```bash
-$ vela status testapp
-About:
-
-  Name:      	testapp
-  Namespace: 	default
-  Created at:	...
-  Updated at:	...
-
-Services:
-
-  - Name: express-server
-    Type: webservice
-    HEALTHY Ready: 1/1
-    Last Deployment:
-      Created at: ...
-      Updated at: ...
-    Routes:
-      - route: 	Visiting URL: http://example.com	IP: <ingress-IP-address>
-```
-
-**In [kind cluster setup](../../install.md#kind)**, you can visit the service via localhost:
-
-> If not in kind cluster, replace localhost with ingress address
-
-```
-$ curl -H "Host:example.com" http://localhost/testapp
-Hello World
-```
-
-## 4. Add auto scaling
-
-```yaml
-name: testapp
-
-services:
-  express-server:
-    ...
-
-    autoscale:
-      minReplicas: 1
-      maxReplicas: 4
-      cron:
-        startAt:  "14:00"
-        duration: "2h"
-        days:     "Monday, Thursday"
-        replicas: "2"
-        timezone: "America/Seattle"
-```
-
-## [Optional] Configure "task" workload type
-
-By now we have deployed a *webservice* workload. We can also add a *task* workload in appfile:
-
-> Below is a simplified [k8s job example](https://kubernetes.io/docs/concepts/workloads/controllers/job/#running-an-example-job) using Vela:
-
-```yaml
-services:
-  pi:
-    image: perl 
-    cmd: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
-
-  express-server:
-    ...
-```
-
-Then deploy appfile again:
-
-```bash
-$ vela up
-```
-
-## What's Next?
-
-Congratulations! You have just deployed an app using Vela.
-
-Here are some next steps that you can have more play with your app:
-
-- [Check Application Logs](../check-logs.md)
-- [Execute Commands in Container](../exec-cmd.md)
-- [Port Forward to Container](../port-forward.md)
-
-
-## References
-
-For more configuration options of built-in capabilities, check [references](../references/README.md)

docs/en/developers/learn-appfile.md

@@ -0,0 +1,179 @@
+# Learning Appfile Step by Step
+
+Appfile is the main user interface to configure application deployment on Vela.
+
+In this tutorial, we will build and deploy an example NodeJS app under [examples/testapp/](https://github.com/oam-dev/kubevela/tree/master/docs/examples/testapp).
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) installed on the host
+- [KubeVela](../install.md) installed and configured
+
+## 1. Download test app code
+
+git clone and go to the testapp directory:
+
+```bash
+$ git clone https://github.com/oam-dev/kubevela.git
+$ cd kubevela/docs/examples/testapp
+```
+
+The example contains NodeJS app code, Dockerfile to build the app.
+
+## 2. Deploy app in one command
+
+In the directory there is a [vela.yaml](https://github.com/oam-dev/kubevela/tree/master/docs/examples/testapp/vela.yaml) which follows Appfile format supported by Vela.
+We are going to use it to build and deploy the app.
+
+> NOTE: please change `oamdev` to your own registry account so you can push. Or, you could try the alternative approach in `Local testing without pushing image remotely` section.
+
+```yaml
+    image: oamdev/testapp:v1 # change this to your image
+```
+
+Run the following command:
+
+```bash
+$ vela up
+Parsing vela.yaml ...
+Loading templates ...
+
+Building service (express-server)...
+Sending build context to Docker daemon  71.68kB
+Step 1/10 : FROM mhart/alpine-node:12
+ ---> 9d88359808c3
+...
+
+pushing image (oamdev/testapp:v1)...
+...
+
+Rendering configs for service (express-server)...
+Writing deploy config to (.vela/deploy.yaml)
+
+Applying deploy configs ...
+Checking if app has been deployed...
+App has not been deployed, creating a new deployment...
+✅ App has been deployed 🚀🚀🚀
+    Port forward: vela port-forward testapp
+             SSH: vela exec testapp
+         Logging: vela logs testapp
+      App status: vela status testapp
+  Service status: vela status testapp --svc express-server
+```
+
+
+Check the status of the service:
+
+```bash
+$ vela status testapp
+  About:
+  
+    Name:       testapp
+    Namespace:  default
+    Created at: 2020-11-02 11:08:32.138484 +0800 CST
+    Updated at: 2020-11-02 11:08:32.138485 +0800 CST
+  
+  Services:
+  
+    - Name: express-server
+      Type: webservice
+      HEALTHY Ready: 1/1
+      Last Deployment:
+        Created at: 2020-11-02 11:08:33 +0800 CST
+        Updated at: 2020-11-02T11:08:32+08:00
+      Routes:
+
+```
+
+### Alternative: Local testing without pushing image remotely
+
+If you have local [kind](../install.md) cluster running, you may try the local push option. No remote container registry is needed in this case.
+
+Add local option to `build`:
+
+```yaml
+    build:
+      # push image into local kind cluster without remote transfer
+      push:
+        local: kind
+
+      docker:
+        file: Dockerfile
+        context: .
+```
+
+Then deploy the app to kind:
+
+```bash
+$ vela up
+```
+
+<details><summary>(Advanced) Check rendered manifests</summary>
+
+By default, Vela renders the final manifests in `.vela/deploy.yaml`:
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: testapp
+  namespace: default
+spec:
+  components:
+  - componentName: express-server
+---
+apiVersion: core.oam.dev/v1alpha2
+kind: Component
+metadata:
+  name: express-server
+  namespace: default
+spec:
+  workload:
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+      name: express-server
+    ...
+---
+apiVersion: core.oam.dev/v1alpha2
+kind: HealthScope
+metadata:
+  name: testapp-default-health
+  namespace: default
+spec:
+  ...
+```
+</details>
+
+## [Optional] Configure another workload type
+
+By now we have deployed a *[Web Service](references/workload-types/web-service.md)*, which is the default workload type in KubeVela. We can also add another service of *[Task](references/workload-types/task.md)* type in the same app:
+
+```yaml
+services:
+  pi:
+    type: task
+    image: perl 
+    cmd: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
+
+  express-server:
+    ...
+```
+
+Then deploy Appfile again to update the application:
+
+```bash
+$ vela up
+```
+
+> Interested in the more details of Appfile? [Learn Full Schema of Appfile](references/devex/appfile.md)
+
+## What's Next?
+
+Congratulations! You have just deployed an app using Vela.
+
+Some tips that you can have more play with your app:
+- [Check Application Logs](./check-logs.md)
+- [Execute Commands in Application Container](./exec-cmd.md)
+- [Access Application via Route](./port-forward.md)
+

docs/en/developers/port-forward.md

@@ -1,12 +1,21 @@
-# Port Forward to Container
+# Port Forwarding
 
-Run:
+Once your web services of the application deployed, you can access it locally via `port-forward`. 
 
+```bash
+$ vela svc ls
+NAME  	        APP  	WORKLOAD  	  TRAITS	STATUS 	    CREATED-TIME
+express-server	testapp	webservice	      	    Deployed	2020-09-18 22:42:04 +0800 CST
 ```
+
+It will directly open browser for you.
+
+```bash
 $ vela port-forward testapp
-Forwarding from 127.0.0.1:8080 -> 8080
-Forwarding from [::1]:8080 -> 8080
+Forwarding from 127.0.0.1:8080 -> 80
+Forwarding from [::1]:8080 -> 80
 
 Forward successfully! Opening browser ...
 Handling connection for 8080
-```
+Handling connection for 8080
+```

docs/en/developers/references/README.md

@@ -1,9 +1,8 @@
-# KubeVela Capability References
+# Capability Documentation
 
-- [workload types](https://github.com/oam-dev/kubevela.io/tree/master/en/developers/references/workload-types)
-- [trait](https://github.com/oam-dev/kubevela.io/tree/master/en/developers/references/traits)
+> Note: All the contents under this directory are designed to be referenced by other documentations as the full schema or usage of specific workload types or traits. 
 
+Learning the detailed schema of every [workload type](https://github.com/oam-dev/kubevela/tree/master/docs/en/developers/references/workload-types)
+and [trait](https://github.com/oam-dev/kubevela/tree/master/docs/en/developers/references/traits) supported in KubeVela.
 
-Note: All the contents under this directory are designed to be referenced by other documentations as the full schema or usage of specific workload types or traits.
-
-In the upcoming releases, we plan to auto-generate all these reference documentations from the CUE templates in KubeVela's definition objects.
+> In the upcoming releases, we plan to auto-generate all these reference documentations from the CUE templates in KubeVela's definition objects, and developers could read them by simply `$ vela show <trait_name>`.

docs/en/developers/references/devex/appfile.md

@@ -0,0 +1,45 @@
+# Appfile
+
+## Description
+
+Appfile is the single source-of-truth of the application description in KubeVela. It captures the application architecture and behaviors of its components following Open Application Model.
+
+Before learning about Appfile's detailed schema, we recommend you to get familiar with core [concepts and glossaries](../../../concepts.md) in KubeVela.
+
+## Schema
+
+List of all available sections for Appfile.
+
+```yaml
+name: _app-name_
+
+services:
+  _service-name_:
+    # If `build` section exists, this field will be used as the name to build image. Otherwise, KubeVela will try to pull the image with given name directly.
+    image: oamdev/testapp:v1
+
+    build:
+      docker:
+        file: _Dockerfile_path_ # relative path is supported, e.g. "./Dockerfile"
+        context: _build_context_path_ # relative path is supported, e.g. "."
+
+      push:
+        local: kind # optionally push to local KinD cluster instead of remote registry
+
+    type: webservice (default) | worker | task
+
+    # detailed configurations of workload
+    ... properties of the specified workload  ...
+
+    _trait_1_:
+      # properties of trait 1
+
+    _trait_2_:
+      # properties of trait 2
+
+    ... more traits and their properties ...
+  
+  _another_service_name_: # more services can be defined
+    ...
+  
+```

docs/en/developers/references/devex/cli.md

@@ -1,7 +1,5 @@
 # KubeVela CLI
 
-Learn about general configurations for `vela` command line tool. For the usage of the CLI, please check the KubeVela's [user documentation](../../README.md) instead.
-
 ### Auto-completion
 
 #### bash

docs/en/developers/references/traits/autoscale.md

@@ -0,0 +1,45 @@
+## Description
+
+`Autoscale` is used to automatically scale workloads by resource utilization metrics and cron
+
+## Specification
+
+List of all available properties for a `Autoscale` trait.
+
+```yaml
+name: testapp
+
+services:
+express-server:
+
+  autoscale:
+    min: 1
+    max: 4
+    cron:
+      startAt:  "14:00"
+      duration: "2h"
+      days:     "Monday, Thursday"
+      replicas: 2
+      timezone: "America/Los_Angeles"
+    cpuPercent: 10
+```
+
+## Properties
+
+Name | Type  | Description | Notes
+------------  | ------------- | ------------- | ------------- 
+ min | int |  minimal replicas of the workload | required 
+ max | int |  maximal replicas of the workload | required 
+ cpuPercent | int |  specify the value for CPU utilization, like 80, which means 80% |  
+ cron | [{Cron}](#Cron) |  just for `appfile`, not available for Cli usage |  
+
+### Cron
+
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | ------------- 
+ startAt | string |  the time to start scaling, like `08:00` |  
+ duration | string |  for how long the scaling will last |  
+ days | string |  several workdays or weekends, like "Monday, Tuesday" |  
+ replicas | int |  the target replicas to be scaled to |  
+ timezone | string |  timezone, like "America/Los_Angeles" |  
+

docs/en/developers/references/traits/metrics.md

@@ -1,10 +1,32 @@
 # Metrics
 
+## Description
+
+`Metrics` is used to configure monitoring metrics to your service.
+
+## Specification
+
+List of all available properties for a `Route` trait.
+
+```yaml
+name: my-app-name
+
+services:
+  my-service-name:
+    ...
+    metrics:
+      format: "prometheus"
+      port: 8080
+      path: "/metrics"
+      scheme:  "http"
+      enabled: true
+```
+
 ## Properties
 
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
-**Path** | **string** | the metric path of the service | [default to /metrics]
+**Path** | **string** | the metrics path of the service | [default to /metrics]
 **Format** | **string** | +format of the metrics, default as prometheus | [default to prometheus]
 **Scheme** | **string** |  | [default to http]
 **Enabled** | **bool** |  | [default to true]

docs/en/developers/references/traits/rollout.md

@@ -0,0 +1,54 @@
+# Rollout
+
+## Description
+
+`Rollout` is used to configure Canary deployment strategy to your application.
+
+## Conflicts With
+
+### `Autoscale`
+
+When `Rollout` and `Autoscle` traits are attached to the same service, they two will fight over the number of instances during rollout. Thus, it's by design that `Rollout` will take over replicas control (specified by `.replicas` field) during rollout.
+
+> Note: in up coming releases, KubeVela will introduce a separate section in Appfile to define release phase configurations such as `Rollout`.
+
+## Specification
+
+List of all available properties for a `Rollout` trait.
+
+```yaml
+servcies:
+  express-server:
+    ...
+
+    rollout:
+      replicas: 2
+      stepWeight: 50
+      interval: "10s"
+```
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**replicas** | **string** | replicas number of the service instance per revision | [ default to 2 ]
+**stepWeight** | **string** | canary increment step percentage (0-100)| [default to 50 ]
+**interval** | **string** | wait interval for every rolling update step | [default to '30s'] 
+
+## How `Rollout` works?
+
+`Rollout` trait implements progressive release process to rollout your app following [Canary strategy](https://martinfowler.com/bliki/CanaryRelease.html).
+
+In detail, `Rollout` controller will create a canary of your app , and then gradually shift traffic to the canary while measuring key performance indicators like HTTP requests success rate at the same time. 
+
+
+![alt](../../../../resources/traffic-shifting-analysis.png)
+
+In this sample, for every `10s`, `5%` traffic will be shifted to canary from the primary, until the traffic on canary reached `50%`. At the mean time, the instance number of canary will automatically scale to `replicas: 2` per configured in Appfile.
+
+
+Based on analysis result of the KPIs during this traffic shifting, a canary will be promoted or aborted if analysis is failed. If promoting, the primary will be upgraded from v1 to v2, and traffic will be fully shifted back to the primary instances. So as result, canary instances will be deleted after the promotion finished.
+
+![alt](../../../../resources/promotion.png)
+
+> Note: KubeVela's `Rollout` trait is implemented with [Weaveworks Flagger](https://flagger.app/) operator.

docs/en/developers/references/traits/route.md

@@ -1,11 +1,33 @@
 # Route
 
+## Description
+
+`Route` is used to configure external access to your service.
+
+## Specification
+
+List of all available properties for a `Route` trait.
+
+```yaml
+name: my-app-name
+
+services:
+  my-service-name:
+    ...
+    route:
+      domain: example.com
+      issuer: tls
+      rules:
+        - path: /testapp
+          rewriteTarget: /
+```
+
 ## Properties
 
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
-**Domain** | **string** |  | [default to ]
-**Issuer** | **string** |  | [default to ]
+**Domain** | **string** | specify your host url for this app | [ default to (empty) ]
+**Issuer** | **string** | specify your certificate issue  | [default to no tls]
 **Rules** | [**[]RouteRules**](#routerules) |  | [optional] 
 
 
@@ -13,5 +35,5 @@ Name | Type | Description | Notes
 
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
-**Path** | **string** |  | 
-**RewriteTarget** | **string** |  | [default to ]
+**Path** | **string** |  | [ default to (empty) ]
+**RewriteTarget** | **string** |  | [ default to (empty) ]

docs/en/developers/references/traits/scale.md

@@ -1,5 +1,23 @@
 # Scaler
 
+## Description
+
+`Scaler` is used to configure replicas to your service.
+
+## Specification
+
+List of all available properties for a `Scaler` trait.
+
+```yaml
+name: my-app-name
+
+services:
+  my-service-name:
+    ...
+    scaler:
+      replicas: 100
+```
+
 ## Properties
 
 Name | Type | Description | Notes

docs/en/developers/references/workload-types/backend-worker.md

@@ -1,6 +1,24 @@
 # Worker
 
-## Properties
+## Description
+
+`Worker` is a workload type to describe long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic.
+
+## Specification
+
+List of all configuration options for a `Worker` workload type.
+
+```yaml
+name: my-app-name
+
+services:
+  my-service-name:
+    type: worker
+    image: oamdev/testapp:v1
+    cmd: ["node", "server.js"]
+```
+
+## Parameters
 
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------