Merge pull request #672 from wonderflow/refine6

refine docs and refactor the arch

docs/contributor/code-contribute.md

@@ -229,7 +229,7 @@ If the pull request fixes a bug:
 
 - The pull request description must include `Closes #<issue number>` or `Fixes #<issue number>`.
 - To avoid regressions, the pull request should include tests that replicate the fixed bug.
-- If this pull request fixes a bug that needs to backport releases, you can add `backport release-x.x` label to automatically backport this PR to release-x.x branch.
+- Generally, we will maintain the last 2 releases for bugfix. You should add `backport release-x.x` label or comment `/backport release-x.y` for the releases contained the bug, github bot will automatically backport this PR to the specified release branch after PR merged. If there're any conflicts, you should cherry-pick it manually.
 
 ## Code review
 
@@ -359,6 +359,7 @@ Before merge, All test CI should pass green.
 
     Signed-off-by: Random Developer <random@developer.example.org>
     ```
+
 ## Update the docs & website
 
 If your pull request merged and this is a new feature or enhancement, it's necessary to update the docs and send a pull request to [kubevela.io](https://github.com/kubevela/kubevela.io) repo.

docs/contributor/release-process.md

@@ -7,7 +7,7 @@ KubeVela is being developed using the following process:
 * Maintainers commit to work on set of features and enhancements and create GitHub milestone to track the work.
 * We are trying to avoid delaying release and prefer moving the feature into the next release if we cannot complete it on time.
 * The new release is published every **2 month**.
-* Critical bug-fixes are cherry-picked into the release branch and delivered using patch releases as frequently as needed.
+* Critical bug-fixes are cherry-picked into the release branch and delivered using patch releases as frequently as needed, we will maintain the last **2 releases**.
 
 ![develop-flow](../resources/develop-code-flow.jpg)
 

docs/getting-started/architecture.md

@@ -4,24 +4,18 @@ title: Architecture
 
 The overall architecture of KubeVela is shown as below:
 
-![alt](../resources/system-arch.jpg)
+![](../resources/vela-overview.jpg)
 
 ## KubeVela is a Control Plane System
 
 KubeVela orchestrates application components, cloud resources and pipeline over multiple clusters and hybrid environments. It is designed to be an application delivery and operation control plane instead of a runtime plugin.
 
-For easy integration with upstream CI pipelines and GitOps tools, KubeVela API (i.e. Open Application Model) are designed as declarative and application-centric, including:
+The [Application concept](./core-concept) is the main KubeVela API, it's designed as declarative and application-centric which can be integrated with upstream CI pipelines and GitOps tools easily.
-
-`Application` for designing application deployment plan.
-
-`Definitions` for managing the abstraction and capabilities of KubeVela with CUE.
-
-- e.g. `ComponentDefinition`, `TraitDefinition`, etc.
 
 In implementation, KubeVela relies on a dedicated Kubernetes cluster to achieve above goals. We chose to rely on Kubernetes as the control plane implementation because this approach is battle tested and brings determinism, convergence and automation to application management at scale. In detail, KubeVela is composed by several parts:
 
 - _KubeVela Core Controller_ that provides the core control logic of the entire system. For example, handling KubeVela API resources, orchestrating workflow, storing revisions, parsing and executing CUE code, garbage collecting, etc.
-- _Addons_ that register and manage definitions along with extended CRD controllers that KubeVela needed to work. For example, Flux and Terraform addons.
+- _Addons_ that register and manage definitions along with extended CRD controllers that KubeVela needed to work. For example, Flux and Terraform addons. The UI console called "App Delivery Platform" in the architecture is also one of the addon.
 
 This control plane Kubernetes cluster will be referenced as the "control plane cluster" in the following documentation.
 
@@ -36,8 +30,6 @@ In real world, application deployment tends to be complex and varies from teams,
 
 ## Who should use KubeVela?
 
-![](../resources/vela-overview.jpg)
-
 - Platform builders for PaaS, Serverless, Application Management/Delivery systems
 	- KubeVela works as an application delivery engine that you could build your advanced platform with.
 - ISV, SaaS owners, and Application Architects who need to distribute software to anywhere
@@ -46,13 +38,13 @@ In real world, application deployment tends to be complex and varies from teams,
 	- VelaUX is an addon of KubeVela, with this addon enabled, it provides an out-of-box modern application Continuous Delivery (CD) and Management platform with an easy-to-use UI console.
 
 
-## What's the relationship between OAM, KubeVela and VelaUX?
+## Conclusion
 
 - [OAM(Open Application Model)](https://github.com/oam-dev/spec) is the model behind KubeVela, it provides a platform-agnostic application model including the best practices and methodology for different vendors to follow. The evolution of the model depends primarily on the practices of KubeVela currently.
-- KubeVela is the core engine running on Kubernetes, it works as a [CRD controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and brings OAM model into your Cloud Native PaaS along with lots of addon capabilities.
+- KubeVela is the control plane running on Kubernetes, it works as a [CRD controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and brings OAM model into your Cloud Native PaaS along with lots of addon capabilities.
-- VelaUX is one of the KubeVela addons, it provides out-of-box application delivery and management platform with **restful API** and **UI console**.
+- VelaUX is the app delivery platform, it's also one of the KubeVela addons, which provides out-of-box application delivery and management capabilities with **restful API** and **UI console**.
 
-The KubeVela team will mainly focus on the core controller. By building VelaUX, we aim to provide out-of-box solutions for small and medium sized companies, and also eat our own dog food and make the extension, integration and the addon system capabilities of KubeVela better. 
+The KubeVela team will mainly focus on the control plane. By building VelaUX, we aim to provide out-of-box solutions for small and medium sized companies, and also eat our own dog food and make the extension, integration and the addon system capabilities of KubeVela better. 
 
 ## Next Step
 

docs/getting-started/definition.md

@@ -30,16 +30,12 @@ When definitions installed in the system, they can be discovered by end user imm
 ```
 $ vela def list
 NAME                         	TYPE                  	NAMESPACE  	DESCRIPTION
-task                         	ComponentDefinition   	vela-system	Describes jobs that run code or a script to completion.
 webservice                   	ComponentDefinition   	vela-system	Describes long-running, scalable, containerized services
                              	                      	           	that have a stable network endpoint to receive external
                              	                      	           	network traffic from customers.
 gateway                      	TraitDefinition       	vela-system	Enable public web traffic for the component, the ingress API
                              	                      	           	matches K8s v1.20+.
-labels                       	TraitDefinition       	vela-system	Add labels on K8s pod for your workload which follows the
-                             	                      	           	pod spec in path 'spec.template'.
 health                       	PolicyDefinition      	vela-system	Apply periodical health checking to the application.
-deploy                       	WorkflowStepDefinition	vela-system	Deploy components with policies.
 notification                 	WorkflowStepDefinition	vela-system	Send message to webhook
 ...snip...
 ```

docs/quick-start.md

@@ -173,7 +173,7 @@ Services:
 
 Great! You have finished deploying your first KubeVela application, you can also view and manage it in UI.
 
-## View and Manage the application from UI
+## Manage application with UI Console
 
 > Currently, the application created by CLI is readonly in your dashboard.
 
@@ -191,13 +191,13 @@ vela port-forward addon-velaux -n vela-system 8080:80
 vela logs -n vela-system --name apiserver addon-velaux | grep "initialized admin username"
 ```
 
-### View resources deployed
+* Check the resources deployed
 
 Click the application card, then you can view the details of the application.
 
 ![](./resources/succeed-first-vela-app.jpg)
 
-## Deleting Application
+## Clean up
 
 ```
 $ vela delete first-vela-app

versioned_docs/version-v1.3/contributor/code-contribute.md

@@ -229,6 +229,7 @@ If the pull request fixes a bug:
 
 - The pull request description must include `Closes #<issue number>` or `Fixes #<issue number>`.
 - To avoid regressions, the pull request should include tests that replicate the fixed bug.
+- Generally, we will maintain the last 2 releases for bugfix. You should add `backport release-x.x` label or comment `/backport release-x.y` for the releases contained the bug, github bot will automatically backport this PR to the specified release branch after PR merged. If there're any conflicts, you should cherry-pick it manually.
 
 ## Code review
 
@@ -346,7 +347,18 @@ Make sure that the title for your pull request uses the same format as the subje
 ### Pass all the CI checks
 
 Before merge, All test CI should pass green.
-The `codecov/project` should also pass. This means the coverage should not drop.
+- The `codecov/project` should also pass. This means the coverage should not drop. Currently, the coverage of the Pull Request should have at least 70%.
+- KubeVela uses [DCO](https://wiki.linuxfoundation.org/dco) for contributor agreements. It requires you to sign-off every commit before the pull request being merged.
+  - Git provides a convenient flag `-s` in your commit command to sign-off automatically:
+    ```shell
+    git commit -s -m 'This is my commit message'
+    ```
+  - Contributors can also sign-off manually by adding a `Signed-off-by` line to commit messages as the following format, make sure the email matches your github account or the check bot won't pass.
+    ```shell
+    This is my commit message
+
+    Signed-off-by: Random Developer <random@developer.example.org>
+    ```
 
 ## Update the docs & website
 

versioned_docs/version-v1.3/contributor/release-process.md

@@ -7,7 +7,7 @@ KubeVela is being developed using the following process:
 * Maintainers commit to work on set of features and enhancements and create GitHub milestone to track the work.
 * We are trying to avoid delaying release and prefer moving the feature into the next release if we cannot complete it on time.
 * The new release is published every **2 month**.
-* Critical bug-fixes are cherry-picked into the release branch and delivered using patch releases as frequently as needed.
+* Critical bug-fixes are cherry-picked into the release branch and delivered using patch releases as frequently as needed, we will maintain the last **2 releases**.
 
 ![develop-flow](../resources/develop-code-flow.jpg)
 

versioned_docs/version-v1.3/getting-started/architecture.md

@@ -4,24 +4,18 @@ title: Architecture
 
 The overall architecture of KubeVela is shown as below:
 
-![alt](../resources/system-arch.jpg)
+![](../resources/vela-overview.jpg)
 
 ## KubeVela is a Control Plane System
 
 KubeVela orchestrates application components, cloud resources and pipeline over multiple clusters and hybrid environments. It is designed to be an application delivery and operation control plane instead of a runtime plugin.
 
-For easy integration with upstream CI pipelines and GitOps tools, KubeVela API (i.e. Open Application Model) are designed as declarative and application-centric, including:
+The [Application concept](./core-concept) is the main KubeVela API, it's designed as declarative and application-centric which can be integrated with upstream CI pipelines and GitOps tools easily.
-
-`Application` for designing application deployment plan.
-
-`Definitions` for managing the abstraction and capabilities of KubeVela with CUE.
-
-- e.g. `ComponentDefinition`, `TraitDefinition`, etc.
 
 In implementation, KubeVela relies on a dedicated Kubernetes cluster to achieve above goals. We chose to rely on Kubernetes as the control plane implementation because this approach is battle tested and brings determinism, convergence and automation to application management at scale. In detail, KubeVela is composed by several parts:
 
 - _KubeVela Core Controller_ that provides the core control logic of the entire system. For example, handling KubeVela API resources, orchestrating workflow, storing revisions, parsing and executing CUE code, garbage collecting, etc.
-- _Addons_ that register and manage definitions along with extended CRD controllers that KubeVela needed to work. For example, Flux and Terraform addons.
+- _Addons_ that register and manage definitions along with extended CRD controllers that KubeVela needed to work. For example, Flux and Terraform addons. The UI console called "App Delivery Platform" in the architecture is also one of the addon.
 
 This control plane Kubernetes cluster will be referenced as the "control plane cluster" in the following documentation.
 
@@ -36,8 +30,6 @@ In real world, application deployment tends to be complex and varies from teams,
 
 ## Who should use KubeVela?
 
-![](../resources/vela-overview.jpg)
-
 - Platform builders for PaaS, Serverless, Application Management/Delivery systems
 	- KubeVela works as an application delivery engine that you could build your advanced platform with.
 - ISV, SaaS owners, and Application Architects who need to distribute software to anywhere
@@ -46,13 +38,13 @@ In real world, application deployment tends to be complex and varies from teams,
 	- VelaUX is an addon of KubeVela, with this addon enabled, it provides an out-of-box modern application Continuous Delivery (CD) and Management platform with an easy-to-use UI console.
 
 
-## What's the relationship between OAM, KubeVela and VelaUX?
+## Conclusion
 
 - [OAM(Open Application Model)](https://github.com/oam-dev/spec) is the model behind KubeVela, it provides a platform-agnostic application model including the best practices and methodology for different vendors to follow. The evolution of the model depends primarily on the practices of KubeVela currently.
-- KubeVela is the core engine running on Kubernetes, it works as a [CRD controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and brings OAM model into your Cloud Native PaaS along with lots of addon capabilities.
+- KubeVela is the control plane running on Kubernetes, it works as a [CRD controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and brings OAM model into your Cloud Native PaaS along with lots of addon capabilities.
-- VelaUX is one of the KubeVela addons, it provides out-of-box application delivery and management platform with **restful API** and **UI console**.
+- VelaUX is the app delivery platform, it's also one of the KubeVela addons, which provides out-of-box application delivery and management capabilities with **restful API** and **UI console**.
 
-The KubeVela team will mainly focus on the core controller. By building VelaUX, we aim to provide out-of-box solutions for small and medium sized companies, and also eat our own dog food and make the extension, integration and the addon system capabilities of KubeVela better. 
+The KubeVela team will mainly focus on the control plane. By building VelaUX, we aim to provide out-of-box solutions for small and medium sized companies, and also eat our own dog food and make the extension, integration and the addon system capabilities of KubeVela better. 
 
 ## Next Step
 

versioned_docs/version-v1.3/getting-started/definition.md

@@ -30,16 +30,12 @@ When definitions installed in the system, they can be discovered by end user imm
 ```
 $ vela def list
 NAME                         	TYPE                  	NAMESPACE  	DESCRIPTION
-task                         	ComponentDefinition   	vela-system	Describes jobs that run code or a script to completion.
 webservice                   	ComponentDefinition   	vela-system	Describes long-running, scalable, containerized services
                              	                      	           	that have a stable network endpoint to receive external
                              	                      	           	network traffic from customers.
 gateway                      	TraitDefinition       	vela-system	Enable public web traffic for the component, the ingress API
                              	                      	           	matches K8s v1.20+.
-labels                       	TraitDefinition       	vela-system	Add labels on K8s pod for your workload which follows the
-                             	                      	           	pod spec in path 'spec.template'.
 health                       	PolicyDefinition      	vela-system	Apply periodical health checking to the application.
-deploy                       	WorkflowStepDefinition	vela-system	Deploy components with policies.
 notification                 	WorkflowStepDefinition	vela-system	Send message to webhook
 ...snip...
 ```

versioned_docs/version-v1.3/quick-start.md

@@ -173,7 +173,7 @@ Services:
 
 Great! You have finished deploying your first KubeVela application, you can also view and manage it in UI.
 
-## View and Manage the application from UI
+## Manage application with UI Console
 
 > Currently, the application created by CLI is readonly in your dashboard.
 
@@ -191,13 +191,13 @@ vela port-forward addon-velaux -n vela-system 8080:80
 vela logs -n vela-system --name apiserver addon-velaux | grep "initialized admin username"
 ```
 
-### View resources deployed
+* Check the resources deployed
 
 Click the application card, then you can view the details of the application.
 
 ![](./resources/succeed-first-vela-app.jpg)
 
-## Deleting Application
+## Clean up
 
 ```
 $ vela delete first-vela-app