Clarify Elasticsearch 9.x compatibility (#2928)

Co-authored-by: Quentin Pradet <[email protected]>
Co-authored-by: Marci W <[email protected]>

Author: 3 people

README.md

@@ -63,24 +63,23 @@ of the getting started documentation.
 
 ## Compatibility
 
-Language clients are forward compatible; meaning that the clients support
-communicating with greater or equal minor versions of Elasticsearch without
-breaking. It does not mean that the clients automatically support new features
-of newer Elasticsearch versions; it is only possible after a release of a new
-client version. For example, a 8.12 client version won't automatically support
-the new features of the 8.13 version of Elasticsearch, the 8.13 client version
-is required for that. Elasticsearch language clients are only backwards
-compatible with default distributions and without guarantees made.
-
-| Elasticsearch Version | Elasticsearch-Python Branch | Supported |
-| --------------------- | ------------------------ | --------- |
-| main                  | main                     |           |
-| 8.x                   | 8.x                      | 8.x       |
-| 7.x                   | 7.x                      | 7.17      |
-
-
-If you have a need to have multiple versions installed at the same time older
-versions are also released as ``elasticsearch7`` and ``elasticsearch8``.
+Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of Elasticsearch without breaking.
+
+Compatibility does not imply full feature parity. New Elasticsearch features are supported only in equivalent client versions. For example, an 8.12 client fully supports Elasticsearch 8.12 features and works with 8.13 without breaking; however, it does not support new Elasticsearch 8.13 features. An 8.13 client fully supports Elasticsearch 8.13 features.
+
+| Elasticsearch version | elasticsearch-py branch |
+| --- | --- |
+| main | main |
+| 9.x | 9.x |
+| 9.x | 8.x |
+| 8.x | 8.x |
+
+Elasticsearch language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees.
+
+> [!TIP]
+> To upgrade to a new major version, first upgrade Elasticsearch, then upgrade the Python Elasticsearch client.
+
+If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`.
 
 
 ## Documentation

docs/reference/index.md

@@ -56,12 +56,21 @@ For a higher level access with more limited scope, have a look at the DSL module
 
 ## Compatibility [_compatibility]
 
-Language clients are forward compatible; meaning that the clients support communicating with greater or equal minor versions of {{es}} without breaking. It does not mean that the clients automatically support new features of newer {{es}} versions; it is only possible after a release of a new client version. For example, a 8.12 client version won’t automatically support the new features of the 8.13 version of {{es}}, the 8.13 client version is required for that. {{es}} language clients are only backwards compatible with default distributions and without guarantees made.
+Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of {{es}} without breaking. 
 
-| Elasticsearch version | elasticsearch-py branch | Supported |
-| --- | --- | --- |
-| main | main |  |
-| 8.x | 8.x | 8.x |
-| 7.x | 7.x | 7.17 |
+Compatibility does not imply full feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking; however, it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features.
 
-If you have a need to have multiple versions installed at the same time older versions are also released as `elasticsearch7` and `elasticsearch8`.
+| Elasticsearch version | elasticsearch-py branch |
+| --- | --- |
+| main | main |
+| 9.x | 9.x |
+| 9.x | 8.x |
+| 8.x | 8.x |
+
+{{es}} language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees. 
+
+:::{tip}
+To upgrade to a new major version, first upgrade {{es}}, then upgrade the Python {{es}} client.
+:::
+
+If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`.