From f48f6efae0bf1cb5af0b10d951f454dcbd0cf564 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?=
 <szabosteve@gmail.com>
Date: Thu, 22 Feb 2024 13:57:29 +0100
Subject: [PATCH] [DOCS] Adds compatibility matrix to docs and readme.

---
 README.md                  | 19 +++++++++++++++++++
 docs/installation.asciidoc | 17 ++++++++++++++---
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5d34cfa98..fb0d45a32 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,25 @@ of the getting started documentation.
 Refer to the [Connecting section](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/getting-started-js.html#_connecting)
 of the getting started documentation.
 
+## Compatibility
+
+The Elasticsearch client is compatible with currently maintained JS versions.
+
+Language clients are forward compatible; meaning that clients support
+communicating with greater or equal minor versions of Elasticsearch without
+breaking. It does not mean that the client automatically supports 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-JS Branch  | Supported |
+| --------------------- | ------------------------ | --------- |
+| main                  | main                     |           |
+| 8.x                   | 8.x                      | 8.x       |
+| 7.x                   | 7.x                      | 7.17      |
+
 ## Usage
 
 * [Creating an index](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/getting-started-js.html#_creating_an_index)
diff --git a/docs/installation.asciidoc b/docs/installation.asciidoc
index 4fe1f78ab..cd36cf3c2 100644
--- a/docs/installation.asciidoc
+++ b/docs/installation.asciidoc
@@ -74,25 +74,36 @@ of `^7.10.0`).
 [[js-compatibility-matrix]]
 === Compatibility matrix
 
-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 clients support
+communicating with greater or equal minor versions of {es} without breaking. It
+does not mean that the client automatically supports 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.
 
-[%header,cols=2*]
+[%header,cols=3*]
 |===
 |{es} Version
 |Client Version
+|Supported
 
+|`8.x`
 |`8.x`
 |`8.x`
 
 |`7.x`
 |`7.x`
+|`7.17`
 
 |`6.x`
 |`6.x`
+|
 
 |`5.x`
 |`5.x`
+|
 |===