Merge pull request #6737 from EnterpriseDB/DOCS-690-adjust-language-about-mixed-versions-redux

Changes with expanded language

Author: djw-m

product_docs/docs/pgd/4/upgrades/index.mdx

@@ -56,11 +56,18 @@ A rolling upgrade starts with a cluster with all nodes at a prior release,
 then proceeds by upgrading one node at a time to the newer release, until
 all nodes are at the newer release. There should never be more than two versions
 of any component running at the same time, which means the new upgrade must not
-be initiated until the previous upgrade process has fully finished on all nodes.
-
-An upgrade process may take an extended period of time when the user decides
-caution is required to reduce business risk, though it's not recommended
-to run the mixed versions of the software indefinitely.
+be initiated until the previous upgrade process has fully finished on all nodes. 
+
+Where additional caution is required to reduce business risk, more time may be
+required to perform an upgrade. For maximum caution and to reduce the time
+required upgrading production systems, we suggest performing the upgrades in a
+separate test environment first. 
+
+Don't run with mixed versions of the software for any longer than is absolutely
+necessary to complete the upgrade. The longer you run with mixed versions, the
+more likely you are to encounter issues, the more difficult it is to diagnose
+and resolve them.  We recommend upgrading in off peak hours for your business,
+and over a short period of time.
 
 While Rolling Upgrade can be used for upgrading major version of the software
 it is not supported to mix PostgreSQL, EDB Postgres Extended and

product_docs/docs/pgd/5.6/planning/limitations.mdx

@@ -9,13 +9,13 @@ into account when planning your deployment.
 
 ## Nodes
 
--   PGD can run hundreds of nodes, assuming adequate hardware and network. However,
+- PGD can run hundreds of nodes, assuming adequate hardware and network. However,
     for mesh-based deployments, we generally don’t recommend running more than 48
     nodes in one cluster. If you need extra read scalability beyond the 48-node
     limit, you can add subscriber-only nodes without adding connections to the
     mesh network.
 
--   The minimum recommended number of nodes in a group is three to provide fault
+- The minimum recommended number of nodes in a group is three to provide fault
     tolerance for PGD's consensus mechanism. With just two nodes, consensus would
     fail if one of the nodes were unresponsive. Consensus is required for some PGD
     operations, such as distributed sequence generation. For more information about
@@ -76,9 +76,32 @@ and current listing.
 
 ## Mixed PGD versions
 
-PGD was developed to [enable rolling upgrades of PGD](/pgd/latest/upgrades) by allowing mixed versions of PGD to operate during the upgrade process. 
-We expect users to run mixed versions only during upgrades and, once an upgrade starts, that they complete that upgrade.
-We don't support running mixed versions of PGD except during an upgrade.
+While PGD was developed to [enable rolling upgrades of
+PGD](/pgd/latest/upgrades) by allowing mixed versions of PGD to operate during
+the upgrade process, we expect users to run mixed versions only during upgrades
+and for users to complete their upgrades as quickly as possible. We also
+recommend that you test any rolling upgrade process in a non-production
+environment before attempting it in production.
+
+When a node is upgraded, it returns to the cluster and communicates with the
+other nodes in the cluster using the lowest version of the inter-node protocol
+that is supported by all the other nodes in the cluster. This means that the
+upgraded node will be able to communicate with all other nodes in the cluster,
+but it will not be able to take advantage of any new features or improvements
+that were introduced in the newer version of PGD. 
+
+That will stay the case until all nodes in the cluster have been upgraded to the
+same newer version.  The longer you run mixed versions, the longer you will be
+without the benefits of the new version, and the longer you will be exposed to
+any potential interoperability issues that might arise from running mixed
+versions. Mixed version clusters are not supported for extended periods of time.
+
+Therefore, once an PGD cluster upgrade has begun, you should complete the whole
+cluster upgrade as quickly as possible.
+
+We don't support running mixed versions of PGD except during an upgrade, and we don't support clusters running mixed versions even while being upgraded, for extended periods.
+
+For more information on rolling upgrades and mixed versions, see [Rolling upgrade considerations](/pgd/latest/upgrades/manual_overview#rolling-upgrade-considerations).
 
 ## Other limitations
 

product_docs/docs/pgd/5.6/upgrades/manual_overview.mdx

@@ -57,16 +57,21 @@ A rolling upgrade starts with a cluster with all nodes at a prior release. It
 then proceeds by upgrading one node at a time to the newer release, until all
 nodes are at the newer release. There must be no more than two versions of the
 software running at the same time. An upgrade must be completed, with all nodes
-fully upgraded, before starting another upgrade.
+fully upgraded, before starting another upgrade. 
 
-An upgrade process can take more time when 
-caution is required to reduce business risk. However, we don't recommend
-running mixed versions of the software indefinitely.
+Where additional caution is required to reduce business risk, more time may be required to perform an upgrade.
+For maximum caution and to reduce the time required upgrading production systems, we suggest performing the upgrades in a separate test environment first.
 
-While you can use a rolling upgrade for upgrading a major version of the software,
-we don't support mixing PostgreSQL, EDB Postgres Extended, and
-EDB Postgres Advanced Server in one cluster. So you can't use this approach 
-to change the Postgres variant.
+Don't run with mixed versions of the software for any longer than is absolutely necessary to complete the upgrade.
+You can check on the versions in the cluster using the [`pgd show-version`](/pgd/5.6/cli/command_ref/pgd_show-version/)
+command. The longer you run with mixed versions, the more likely you are to
+encounter issues, the more difficult it is to diagnose and resolve them.  
+We recommend upgrading in off peak hours for your business, and over a short period of time.
+
+While you can use a rolling upgrade for upgrading a major version of the
+software, we don't support mixing PostgreSQL, EDB Postgres Extended, and EDB
+Postgres Advanced Server in one cluster. So you can't use this approach to
+change the Postgres variant.
 
 !!! Warning
     Downgrades of EDB Postgres Distributed aren't supported. They require

product_docs/docs/pgd/5.7/planning/limitations.mdx

@@ -9,13 +9,13 @@ into account when planning your deployment.
 
 ## Nodes
 
--   PGD can run hundreds of nodes, assuming adequate hardware and network. However,
+- PGD can run hundreds of nodes, assuming adequate hardware and network. However,
     for mesh-based deployments, we generally don’t recommend running more than 48
     nodes in one cluster. If you need extra read scalability beyond the 48-node
     limit, you can add subscriber-only nodes without adding connections to the
     mesh network.
 
--   The minimum recommended number of nodes in a group is three to provide fault
+- The minimum recommended number of nodes in a group is three to provide fault
     tolerance for PGD's consensus mechanism. With just two nodes, consensus would
     fail if one of the nodes were unresponsive. Consensus is required for some PGD
     operations, such as distributed sequence generation. For more information about
@@ -76,9 +76,21 @@ and current listing.
 
 ## Mixed PGD versions
 
-PGD was developed to [enable rolling upgrades of PGD](/pgd/latest/upgrades) by allowing mixed versions of PGD to operate during the upgrade process. 
-We expect users to run mixed versions only during upgrades and, once an upgrade starts, that they complete that upgrade.
-We don't support running mixed versions of PGD except during an upgrade.
+While PGD was developed to [enable rolling upgrades of PGD](/pgd/latest/upgrades) by allowing mixed versions of PGD to operate during the upgrade process, we expect users to run mixed versions only during upgrades and for users to complete their upgrades as quickly as possible.
+We also recommend that you test any rolling upgrade process in a non-production environment before attempting it in production.
+
+When a node is upgraded, it returns to the cluster and communicates with the other nodes in the cluster using the lowest version of the inter-node protocol that is supported by all the other nodes in the cluster. 
+This means that the upgraded node will be able to communicate with all other nodes in the cluster, but it will not be able to take advantage of any new features or improvements that were introduced in the newer version of PGD.
+
+That will stay the case until all nodes in the cluster have been upgraded to the same newer version.  
+The longer you run mixed versions, the longer you will be without the benefits of the new version, and the longer you will be exposed to any potential interoperability issues that might arise from running mixed versions.
+Mixed version clusters are not supported for extended periods of time.
+
+Therefore, once an PGD cluster upgrade has begun, you should complete the whole cluster upgrade as quickly as possible.
+
+We don't support running mixed versions of PGD except during an upgrade, and we don't support clusters running mixed versions even while being upgraded, for extended periods.
+
+For more information on rolling upgrades and mixed versions, see [Rolling upgrade considerations](/pgd/latest/upgrades/manual_overview#rolling-upgrade-considerations).
 
 ## Other limitations
 

product_docs/docs/pgd/5.7/upgrades/manual_overview.mdx

@@ -59,9 +59,13 @@ nodes are at the newer release. There must be no more than two versions of the
 software running at the same time. An upgrade must be completed, with all nodes
 fully upgraded, before starting another upgrade.
 
-An upgrade process can take more time when 
-caution is required to reduce business risk. However, we don't recommend
-running mixed versions of the software indefinitely.
+Where additional caution is required to reduce business risk, more time may be required to perform an upgrade. 
+For maximum caution and to reduce the time required upgrading production systems, we suggest performing the upgrades in a separate test environment first.
+
+Don't run with mixed versions of the software for any longer than is absolutely necessary to complete the upgrade. 
+You can check on the versions in the cluster using the [`pgd nodes list --versions`](/pgd/5.7/cli/command_ref/nodes/list/) command.
+The longer you run with mixed versions, the more likely you are to encounter issues, the more difficult it is to diagnose and resolve them.  
+We recommend upgrading in off peak hours for your business, and over a short period of time.
 
 While you can use a rolling upgrade for upgrading a major version of the software,
 we don't support mixing PostgreSQL, EDB Postgres Extended, and