Browse Source

Improve docs for pre-release version compatibility (#78428)

* Improve docs for pre-release version compatibility

Follow-up to #78317 clarifying a couple of points:

- a pre-release build can restore snapshots from released builds
- compatibility applies if at least one of the local or remote cluster
  is a released build

* Remote cluster build date nit
David Turner 4 years ago
parent
commit
07a2acac93

+ 8 - 6
docs/reference/modules/remote-clusters-shared.asciidoc

@@ -13,12 +13,14 @@ h| Remote cluster | 5.0->5.5 | 5.6 | 6.0->6.6 | 6.7 | 6.8 | 7.0 | 7.1->7.x
 |====
 |====
 
 
 ifeval::["{release-state}"!="released"]
 ifeval::["{release-state}"!="released"]
-NOTE: This documentation is for {es} {version}, which is not yet released. The
-above compatibility table only applies if the local or remote cluster is running
-a released version of {es}. A local cluster running a pre-release build of {es}
-can also communicate with remote clusters running the same pre-release build.
-Running a mix of pre-release builds is unsupported and typically will not work,
-even if the builds are the same version.
+NOTE: This documentation is for {es} version {version}, which is not yet
+released. The above compatibility table applies if both clusters are running a
+released version of {es}, or if one of the clusters is running a released
+version and the other is running a pre-release build with a later build date. A
+cluster running a pre-release build of {es} can also communicate with remote
+clusters running the same pre-release build. Running a mix of pre-release
+builds is unsupported and typically will not work, even if the builds have the
+same version number.
 endif::[]
 endif::[]
 
 
 // end::remote-cluster-compatibility-matrix[]
 // end::remote-cluster-compatibility-matrix[]

+ 10 - 7
docs/reference/snapshot-restore/index.asciidoc

@@ -96,16 +96,19 @@ The one caveat is that snapshots taken by {es} 2.0 can be restored in clusters r
 
 
 ifeval::["{release-state}"!="released"]
 ifeval::["{release-state}"!="released"]
 [[snapshot-prerelease-build-compatibility]]
 [[snapshot-prerelease-build-compatibility]]
-NOTE: This documentation is for {es} {version}, which is not yet released. The
-compatibility table above applies only to snapshots taken in a released version
-of {es}. If you're testing a pre-release build of {es} then you can also take
-and restore snapshots as normal, but you must not use the same snapshot
-repository with other builds of {es} even if the builds are the same version.
+NOTE: This documentation is for {es} version {version}, which is not yet
+released. The compatibility table above applies only to snapshots taken in a
+released version of {es}. If you're testing a pre-release build of {es} then you
+can still restore snapshots taken in earlier released builds as permitted by
+this compatibility table. You can also take snapshots using your pre-release
+build, and restore them using the same build. However once a pre-release build
+of {es} has written to a snapshot repository you must not use the same
+repository with other builds of {es}, even if the builds have the same version.
 Different pre-release builds of {es} may use different and incompatible
 Different pre-release builds of {es} may use different and incompatible
 repository layouts. If the repository layout is incompatible with the {es} build
 repository layouts. If the repository layout is incompatible with the {es} build
 in use then taking and restoring snapshots may result in errors or may appear to
 in use then taking and restoring snapshots may result in errors or may appear to
-succeed having silently lost some data. You should discard the repository when
-moving to a different build.
+succeed having silently lost some data. You should discard your repository
+before using a different build.
 endif::[]
 endif::[]
 
 
 Each snapshot can contain indices created in various versions of {es}. This
 Each snapshot can contain indices created in various versions of {es}. This

+ 8 - 8
docs/reference/upgrade.asciidoc

@@ -89,14 +89,14 @@ of the products in your Elastic Stack. For more information, see the
 
 
 ifeval::["{release-state}"!="released"]
 ifeval::["{release-state}"!="released"]
 [[upgrade-pre-release]]
 [[upgrade-pre-release]]
-NOTE: This documentation is for {es} {version}, which is not yet released. You
-may run a pre-release build of {es} for testing, and you may upgrade from an
-earlier released version to a pre-release build of {es} {version} if permitted
-by the compatibility table above, but upgrading from a pre-release build to
-another build (whether released or not) is unsupported. Upgrading a pre-release
-build may result in errors or may appear to succeed having silently lost some
-data. You should discard the contents of a cluster running a pre-release build
-when moving to a different build.
+NOTE: This documentation is for {es} version {version}, which is not yet
+released. You may run a pre-release build of {es} for testing, and you may
+upgrade from an earlier released version to a pre-release build of {es}
+{version} if permitted by the compatibility table above, but upgrading from a
+pre-release build to another build (whether released or not) is unsupported.
+Upgrading a pre-release build may result in errors or may appear to succeed
+having silently lost some data. You should discard the contents of a cluster
+running a pre-release build before using a different build.
 endif::[]
 endif::[]
 
 
 --
 --