Add docs for pre-release version compatibility (#78317)

The reference manual includes docs on version compatibility in various
places, but it's not clear that these docs only apply to released
versions and that the rules for pre-release versions are stricter than
folks expect. This commit adds some words to the docs for unreleased
versions which explains this subtlety.

docs/reference/ccr/index.asciidoc

@@ -32,7 +32,7 @@ If newer, the versions must also be compatible as outlined in the following matr
 [[ccr-version-compatibility]]
 .Version compatibility matrix
 ====
-include::../modules/remote-clusters.asciidoc[tag=remote-cluster-compatibility-matrix]
+include::../modules/remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix]
 ====
 
 [discrete]

docs/reference/modules/remote-clusters-shared.asciidoc

@@ -0,0 +1,24 @@
+// tag::remote-cluster-compatibility-matrix[]
+[cols="^,^,^,^,^,^,^,^"]
+|====
+| 7+^h| Local cluster
+h| Remote cluster | 5.0->5.5 | 5.6 | 6.0->6.6 | 6.7 | 6.8 | 7.0 | 7.1->7.x
+| 5.0->5.5      | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} | {no-icon}  | {no-icon} | {no-icon}
+| 5.6           | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon}
+| 6.0->6.6      | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon}
+| 6.7           | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon}
+| 6.8           | {no-icon} | {yes-icon} |  {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon}
+| 7.0           | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon}
+| 7.1->7.x      | {no-icon} | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon}
+|====
+
+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.
+endif::[]
+
+// end::remote-cluster-compatibility-matrix[]

docs/reference/modules/remote-clusters.asciidoc

@@ -65,20 +65,7 @@ local and remote nodes.
 [%collapsible%open]
 .Version compatibility table
 ====
-// tag::remote-cluster-compatibility-matrix[]
+include::remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix]
-[cols="^,^,^,^,^,^,^,^"]
-|====
-| 7+^h| Local cluster
-h| Remote cluster | 5.0->5.5 | 5.6 | 6.0->6.6 | 6.7 | 6.8 | 7.0 | 7.1->7.x
-| 5.0->5.5      | {yes-icon} | {yes-icon} | {no-icon} | {no-icon} | {no-icon}  | {no-icon} | {no-icon}
-| 5.6           | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon}
-| 6.0->6.6      | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon} | {no-icon}
-| 6.7           | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {no-icon}
-| 6.8           | {no-icon} | {yes-icon} |  {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon}
-| 7.0           | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon} | {yes-icon}
-| 7.1->7.x      | {no-icon} | {no-icon} | {no-icon} | {no-icon} | {yes-icon} | {yes-icon} | {yes-icon}
-|====
-// end::remote-cluster-compatibility-matrix[]
 ====
 
 * *role*: Dedicated master nodes are never selected as gateway nodes.
@@ -100,7 +87,16 @@ to the sniff <<gateway-nodes-selection,gateway nodes>>, the remote
 connections are subject to the same version compatibility rules as
 <<rolling-upgrades,rolling upgrades>>.
 
+Proxy mode has the same version compatibility requirements as sniff mode.
+
+[%collapsible]
+[[proxy-mode-version-compatibility]]
+.Version compatibility matrix
+====
+include::remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix]
+====
+
 include::cluster/remote-clusters-security.asciidoc[]
 include::cluster/remote-clusters-connect.asciidoc[]
 include::../../../x-pack/docs/en/security/authentication/remote-clusters-privileges.asciidoc[]
-include::cluster/remote-clusters-settings.asciidoc[]
+include::cluster/remote-clusters-settings.asciidoc[]

docs/reference/snapshot-restore/index.asciidoc

@@ -94,6 +94,20 @@ The following conditions apply for restoring snapshots and indices across versio
 The one caveat is that snapshots taken by {es} 2.0 can be restored in clusters running {es} 5.0.
 ====
 
+ifeval::["{release-state}"!="released"]
+[[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.
+Different pre-release builds of {es} may use different and incompatible
+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
+succeed having silently lost some data. You should discard the repository when
+moving to a different build.
+endif::[]
+
 Each snapshot can contain indices created in various versions of {es}. This
 includes backing indices created for data streams. When restoring a snapshot, it
 must be possible to restore all of these indices into the target cluster. If any

docs/reference/upgrade.asciidoc

@@ -87,6 +87,18 @@ When upgrading to a new version of {es}, you need to upgrade each
 of the products in your Elastic Stack. For more information, see the
 {stack-ref}/upgrading-elastic-stack.html[Elastic Stack Installation and Upgrade Guide].
 
+ifeval::["{release-state}"!="released"]
+[[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.
+endif::[]
+
 --
 
 include::upgrade/rolling_upgrade.asciidoc[]