[skywalking] 01/01: Provide the new version upgrade documentation/FAQ.

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch upgrade-faq
in repository https://gitbox.apache.org/repos/asf/skywalking.git

commit e1001940c51362e8c6448e410320576534f28d0d
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Tue Feb 4 15:13:16 2020 +0800

    Provide the new version upgrade documentation/FAQ.
---
 docs/en/FAQ/README.md                             |  3 ++-
 docs/en/FAQ/{Upgrade.md => v3-version-upgrade.md} |  3 +--
 docs/en/FAQ/v6-version-upgrade.md                 | 30 +++++++++++++++++++++++
 docs/en/setup/README.md                           |  3 +++
 4 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/docs/en/FAQ/README.md b/docs/en/FAQ/README.md
index 3e0e79f..2f1e110 100644
--- a/docs/en/FAQ/README.md
+++ b/docs/en/FAQ/README.md
@@ -9,10 +9,11 @@ These are known and common FAQs. We welcome you to contribute yours.
 * [Required items could not be found, when import project into Eclipse](Import-Project-Eclipse-RequireItems-Exception.md)
 
 ## Runtime
+* [6.x version upgrade](v6-version-upgrade.md)
 * [Why only traces in UI?](Why-have-traces-no-others.md)
 * [Too many GRPC logs in the console](Too-many-gRPC-logs.md)
 * [The trace doesn't continue in kafka consumer side](kafka-plugin.md)
-* [Agent or collector version upgrade](Upgrade.md)
+* [Agent or collector version upgrade,  3.x -> 5.0.0-alpha](v3-version-upgrade.md)
 * [EnhanceRequireObjectCache class cast exception](EnhanceRequireObjectCache-Cast-Exception.md)
 * [ElasticSearch server performance FAQ, including ERROR CODE:429](ES-Server-FAQ.md)
 * [IllegalStateException when install Java agent on WebSphere 7](install_agent_on_websphere.md)
diff --git a/docs/en/FAQ/Upgrade.md b/docs/en/FAQ/v3-version-upgrade.md
similarity index 90%
rename from docs/en/FAQ/Upgrade.md
rename to docs/en/FAQ/v3-version-upgrade.md
index a6ce1ed..ab4dcb1 100644
--- a/docs/en/FAQ/Upgrade.md
+++ b/docs/en/FAQ/v3-version-upgrade.md
@@ -1,5 +1,4 @@
-# Upgrade FAQs
-## Version 3.x -> 5.0.0-alpha
+## Version 3.x -> 5.0.0-alpha Upgrade FAQs
 ### Collector
 ### Problem
 There is no information showing in the UI.
diff --git a/docs/en/FAQ/v6-version-upgrade.md b/docs/en/FAQ/v6-version-upgrade.md
new file mode 100644
index 0000000..47e7e0d
--- /dev/null
+++ b/docs/en/FAQ/v6-version-upgrade.md
@@ -0,0 +1,30 @@
+# V6 upgrade
+SkyWalking v6 is widely used in many production environments. Users may wants to upgrade to an old release to new.
+This is a guidance to tell users how to do that.
+
+**NOTICE**, the following ways are not the only ways to do upgrade.
+
+## Use Canary Release
+Like all applications, SkyWalking could use `canary release` method to upgrade by following these steps
+1. Deploy a new cluster by using the latest(or new) version of SkyWalking OAP cluster with new database cluster.
+1. Once the target(being monitored) service has chance to upgrade the agent.jar(or just simply reboot), change the `collector.backend_service`
+pointing to the new OAP backend, and use/add a new namespace(`agent.namespace` in [Table of Agent Configuration Properties](../setup/service-agent/java-agent/README.md#table-of-agent-configuration-properties)).
+The namespace will avoid the conflict between different versions.
+1. When all target services have been rebooted, the old OAP clusters could be discarded.
+
+`Canary Release` methods works for any version upgrade.
+
+## Online Hot Reboot Upgrade
+The reason we required `Canary Release` is, SkyWalking agent has cache mechanisms, switching to a new cluster makes the 
+cache unavailable for new OAP cluster.
+In the 6.5.0+(especially for agent version), we have [**Agent hot reboot trigger mechanism**](../setup/backend/backend-setup.md#agent-hot-reboot-trigger-mechanism-in-oap-server-upgrade).
+By using that, we could do upgrade an easier way, **deploy a new cluster by using the latest(or new) version of SkyWalking OAP cluster with new database cluster**,
+and shift the traffic to the new cluster once for all. Based on the mechanism, all agents will go into `cool_down` mode, then
+back online. More detail, read the backend setup document.
+
+**NOTICE**, as a known bug in 6.4.0, its agent could have re-connection issue, so, even this bot reboot mechanism included in 6.4.0,
+it may not work in some network scenarios, especially in k8s.
+
+## Agent Compatibility
+All versions of SkyWalking 6.x(even 7.x) are compatible with each others, so users could not upgrade the agents. 
+The agent is also enhanced from version to version, so from SkyWalking team's recommendations, upgrade the agent once you have the chance.
diff --git a/docs/en/setup/README.md b/docs/en/setup/README.md
index a722eb9..447f4db 100644
--- a/docs/en/setup/README.md
+++ b/docs/en/setup/README.md
@@ -44,3 +44,6 @@ Follow [backend and UI setup document](backend/backend-ui-setup.md) to understan
 ## Changes log
 
 Backend, UI and Java agent changes are available [here](../../../CHANGES.md).
+
+## Upgrade FAQ
+[6.x version upgrade FAQ](../FAQ/v6-version-upgrade.md) introduces the recommendation ways to do SkyWalking upgrade.