[skywalking] branch upgrade-faq created (now e100194)

[wu...@apache.org]

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

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


      at e100194  Provide the new version upgrade documentation/FAQ.

This branch includes the following new commits:

     new e100194  Provide the new version upgrade documentation/FAQ.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[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.