Documentation for LTS Upgradeability (#1103)

Initial draft, based on PRD and TDD, and the resulting Documentation
Plan

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

@@ -5,6 +5,18 @@
 
 {description}
 
+== Best Practices
+
+Before starting a rolling upgrade, consider the following best practices:
+
+* Ensure that the <<hazelcast-members-compatibility-guarantees,Compatibility Guarantees>> cover your requirements
+* If the minimum version of JDK has changed between releases, <<updated-jdk,upgrade the JDK version>> before starting a rolling upgrade
+* If you used Hazelcast Operator to deploy your cluster, refer to the link:https://docs.hazelcast.com/operator/latest/scaling-upgrading#upgrading[Operator documentation, window=_blank]
+* If using Hazelcast Management Center to trigger your rolling upgrade, upgrade Management Center before upgrading your members. For information on upgrading Management Center, refer to the link:https://docs.hazelcast.com/management-center/5.4/getting-started/install[Management Center documentation, window=_blank], or if you deployed Management Center using the Hazelcast Operator, refer to the link:https://docs.hazelcast.com/operator/latest/deploy-management-center.adoc[Operator documentation, window=_blank]
+* If using the `hz-cluster-admin` script to update your cluster, enable the `CLUSTER_WRITE` endpoints in the REST API. For further information on the {community-product-name} REST API, see xref:maintain-cluster:rest-api.adoc#using-the-rest-endpoint-groups[{community-product-name} REST API]. For further information on the {enterprise-product-name} REST API, see xref:maintain-cluster:enterprise-rest-api.adoc#dynamic-configuration-update-rest-endpoint[{enterprise-product-name} REST API]
+* Plan sufficient time for the migration and upgrade to complete, and remember that the members cannot change during the upgrade
+* Avoid issues where an automatic upgrade is triggered before the last member has been upgraded by setting a <<enabling-auto-upgrading,minimum cluster size>>
+
 == Before you Begin
 
 Hazelcast uses semantic versioning, where versions appear in the following format:
@@ -39,7 +51,7 @@ To allow you to use rolling upgrades, Hazelcast commits to the following compati
 - Hazelcast members operating on the same major and minor
 cluster version are always compatible, regardless of patch version.
 
-- Each minor version is always compatible with the previous one.
+- Each minor version is compatible with the previous one.
 
 As a result, you can use rolling upgrades to upgrade clusters to the following member codebase versions:
 
@@ -48,8 +60,23 @@ As a result, you can use rolling upgrades to upgrade clusters to the following m
 +
 This also includes the ability of rolling upgrade from Hazelcast IMDG 4.2 to Platform 5.0, since IMDG is part of the Platform and 5.0 is considered to be the next minor version after IMDG 4.2.
 
+- The 5.5 Long-term Support (LTS) release direct from 5.2.x to 5.4.x. For further information on additional compatibilities for direct-to-LTS rolling upgrades, see xref:migrate:lts.adoc[].
+
 NOTE: Following the rolling upgrade, you must resubmit jobs as they don't run during the upgrade. For further information on the compatibility of job states in upgrades, see xref:deploy:versioning-compatibility.adoc#job-states[Versioning and Compatibility].
 
+=== Upgrade to LTS Release
+
+With the introduction of Hazelcast's first LTS release, you can upgrade directly from 5.2, or later, to 5.5. This means that, if using a supported earlier version, you do not need to upgrade to each version between your current version and the LTS release.
+
+For more information on LTS releases, and any specific considerations when upgrading, see xref:migrate:lts.adoc[].
+
+[[updated-jdk]]
+== JDK Version Upgrade
+
+As newer JDK releases contain improvements, we recommend that you upgrade to a newer JDK version where xref:deploy:versioning-compatibility.adoc#supported-java-virtual-machines[supported].
+
+Upgrade the JDK version before upgrading your members if support for the JDK version has changed between your current and planned cluster versions. For example, in 5.2 JDK 8 or later was supported, but 5.5 supports only JDK 17 or later. 
+
 [[rolling-upgrade-procedure]]
 == Performing a Rolling Upgrade
 
@@ -220,3 +247,16 @@ binary and algorithmic compatibility and some other steps.
 
 It is worth mentioning that a business app upgrade is orthogonal to a
 rolling member upgrade. A rolling business app upgrade may be done without upgrading the members.
+
+**Are features marked as Beta in my current version upgraded?**
+
+Features marked as Beta in the source version are upgraded, but are supported only in a cluster of the same version as the source version due to changes that can occur between releases. 
+
+This means that you can encounter failures if, for example, changes have been made to the field format or where there is a SQL dependency. Following any failure, where the Beta feature has been updated or made generally available in the target version, the updated version of the feature is used.
+
+**Can I upgrade directly to the latest release?**
+
+You can upgrade directly to the latest release in the following circumstances:
+
+* Your source version is no more than one minor version below the latest (target) version
+* The target version is an LTS release and your source version is among those supported for direct-to-LTS upgrades. For further information on LTS releases and the supported source versions, see xref:migrate:lts.adoc[Long-term Releases]

docs/modules/migrate/pages/lts.adoc

@@ -0,0 +1,131 @@
+= Long-term Support Releases
+
+:description: Hazelcast simplifies your upgrade experience with the introduction of long-term support (LTS) releases. You can upgrade directly from a supported previous release to the LTS release or directly between LTS releases using a rolling upgrade.
+:page-enterprise: true
+
+{description}
+
+LTS releases have been introduced with Hazelcast Platform 5.5. You can upgrade directly from 5.2.x or later to 5.5 without the need to upgrade to each release between your current version and the LTS release. We recommend that you upgrade to 5.5 from the latest available patch for your current release.
+
+NOTE: Features marked as Beta in the source version are upgraded, but are supported only in a cluster of the source version due to changes that can occur between releases. For further information on rolling upgrade compatibilities, see xref:maintain-cluster:rolling-upgrades.adoc#hazelcast-members-compatibility-guarantees[Compatibility Guarantees].
+
+Between LTS releases, Hazelcast will provide short-term support (STS) releases. You can choose to upgrade directly from one LTS to the next LTS, or you can upgrade from one LTS to each STS release and then from the last STS release to the next LTS release. Before deciding the approach that best suits your needs, consider the following:
+
+[cols="1,1"]
+|===
+|LTS|STS
+
+|Focus on stability.
+|Focus on innovation.
+
+|Consolidates the functionality introduced in all STS releases since the last LTS release. Can include improvements, such as increased capacity limits.
+|Provides the latest features and bug fixes.
+
+|Released every two years.
+|Released at least twice each year.
+
+|Upgrade directly from the previous LTS, or from the STS release that precedes the latest LTS release.
+|Upgrade from last available STS release only.
+
+For example, if there are three STS releases between LTS releases, you cannot upgrade to the latest LTS unless you have upgraded to all three STS releases. 
+
+|Full support for three years with the option of extended support for a further year.
+|Maintenance support until the next STS or LTS release only.
+
+|Choose if you value stability over new feature adoption, you want to upgrade less frequently, and you want full or extended support.
+|Choose if you value new features over stability, you are willing to upgrade several times a year, and you are happy with maintenance support for the life of the STS.
+|===
+
+== Hazelcast 5.5 LTS
+
+The Hazelcast 5.5 LTS release supports direct upgrade as follows:
+
+[cols="1,1"]
+|===
+|Upgrade From|LTS Release Support
+
+|5.2
+
+5.3
+
+a|* IMap data structure. This includes the API, configuration options, and persistence
+* CP subsystem. This includes the API and peristence
+* WAN replication. Ongoing replication is supported during the upgrade. This includes both source and target; however, the source and the target cannot be upgraded simultaneously
+
+NOTE: Hazelcast has tested WAN Replication to validate the upgrade solution. The test covered two clusters of different versions; for scenarios where WAN Replication is used from a cluster with a version or 5.2, 5.3, or 5.4 to another cluster with a version between 4.0 and 5.4, only the replication to clusters of version 5.2 or later have been tested.
+
+|5.4
+|All features
+|===
+
+== Mixed-version Clusters
+
+Your LTS release member can join clusters that include members from an earlier supported version. You cannot have members from more than two different minor versions in the same cluster.
+
+The following table provides an example of the behaviour:
+
+[cols="1,1,1,1"]
+|===
+|Action|Member Version|Cluster Version|Description
+
+|Form cluster
+|5.2
+|5.2
+|5.2 cluster forms
+
+|Member tries to join cluster
+|5.3
+|5.2
+|5.3 member joins 5.2 cluster
+
+|Further member tries to join cluster
+|LTS
+|5.2
+|LTS member identifies that two different minor versions are already in the cluster and rejects joining the cluster
+|===
+
+The scenario outlined below can occur because the logic for a mixed-version cluster is introduced in the first LTS release and cannot be enforced by earlier releases.
+However, this scenario is not supported and results from such a cluster would not be reliable. 
+
+Hazelcast recommends that you avoid the following scenario:
+
+[cols="1,1,1,1"]
+|===
+|Action|Member Version|Cluster Version|Description
+
+|Form cluster
+|5.2
+|5.2
+|5.2 cluster forms
+
+|Member tries to join cluster
+|LTS
+|5.2
+|Member identifies that only one minor version is already in the cluster and joins the cluster
+
+|Further member tries to join cluster
+|5.3
+|5.2
+|Member joins the cluster
+|===
+
+== High-level Process
+
+The process for upgrading to an LTS release is the same as for a rolling upgrade. To summarize, the process involves the following steps:
+
+. For each member in the cluster:
+
+.. Shut down the member and wait for all partitions to migrate to the rest of the cluster
+.. Upgrade the member's codebase
+.. Start the member and wait for it to join the cluster
+
+. Trigger the rolling upgrade on the cluster
+
+For further information on performing a rolling upgrade, including the steps to take, compatibility guarantees and any constraints, see xref:maintain-cluster:rolling-upgrades.adoc[]. 
+
+=== Restart Members on Previous Version
+
+If the version has not successfully upgraded following an upgrade, you can recover to the previous version by restarting the members.
+This is the case whether the upgrade was done automatically, using the API, or using a script.
+
+To do this, xref:maintain-cluster:shutdown.adoc#shutting-down-a-hazelcast-member[shut down] then start each member.

docs/modules/migrate/partials/nav.adoc

@@ -1,4 +1,5 @@
 ** xref:deploy:versioning-compatibility.adoc[Versioning and Compatibility]
+** xref:migrate:lts.adoc[]
 ** xref:migrate:data-migration-tool.adoc[]
 *** xref:migrate:dmt-command-reference.adoc[]
 ** xref:migrate:migration-tool-imdg.adoc[]