[DOCS] Adds compatibility matrix to docs and readme (elastic#2458)

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

Author: szabosteve

README.rst

@@ -75,12 +75,27 @@ Usage
 Compatibility
 -------------
 
-Language clients are forward compatible; meaning that clients support communicating
-with greater or equal minor versions of Elasticsearch. Elasticsearch language clients
-are only backwards compatible with default distributions and without guarantees made.
+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-py 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 ``elasticsearch2`` and ``elasticsearch5``.
+versions are also released as ``elasticsearch7`` and ``elasticsearch8``.
 
 
 Documentation

docs/guide/installation.asciidoc

@@ -1,9 +1,9 @@
 [[installation]]
 == Installation
 
-**[Download the latest version of Elasticsearch](https://www.elastic.co/downloads/elasticsearch)**
+**https://www.elastic.co/downloads/elasticsearch[Download the latest version of Elasticsearch]**
 or
-**[sign-up](https://cloud.elastic.co/registration?elektra=en-ess-sign-up-page)**
+**https://cloud.elastic.co/registration?elektra=en-ess-sign-up-page[sign-up]**
 **for a free trial of Elastic Cloud**.
 
 The Python client for {es} can be installed with pip:

docs/guide/overview.asciidoc

@@ -10,12 +10,25 @@ on https://elasticsearch-py.readthedocs.io[Read the Docs].
 [discrete]
 === Compatibility
 
-Language clients are forward compatible; meaning that clients support communicating
-with greater or equal minor versions of Elasticsearch. Elasticsearch language clients
-are only backwards compatible with default distributions and without guarantees made.
+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.
+
+|===
+| Elasticsearch version | elasticsearch-py 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 `elasticsearch2` and `elasticsearch5`.
+versions are also released as `elasticsearch7` and `elasticsearch8`.
 
 
 [discrete]

docs/sphinx/index.rst

@@ -34,9 +34,24 @@ Read more about `how to use asyncio with this project <async.html>`_.
 Compatibility
 -------------
 
-Language clients are forward compatible; meaning that clients support communicating
-with greater or equal minor versions of Elasticsearch. Elasticsearch language clients
-are only backwards compatible with default distributions and without guarantees made.
+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-py branch | Supported |
++=======================+=========================+===========+
+| main                  | main                    |           |
++-----------------------+-------------------------+-----------+
+| 8.x                   | 8.x                     | 8.x       |
++-----------------------+-------------------------+-----------+
+| 7.x                   | 7.x                     | 7.17      |
++-----------------------+-------------------------+-----------+
 
 If you need multiple versions installed at the same time, versions are
 also released, such as ``elasticsearch7`` and ``elasticsearch8``.