From f70c97af2f4141c3ed715d33df344153f86139ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?=
 <szabosteve@gmail.com>
Date: Fri, 23 Feb 2024 10:35:10 +0100
Subject: [PATCH] [DOCS] Adds section about version compatibility to overview.
 (#1394)

---
 README.md              | 19 +++++++++++++++++++
 docs/overview.asciidoc | 25 +++++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 7ea3e7e6b..117239386 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,25 @@ the major version of the corresponding Enterprise Search implementation.
 For example, for Elasticsearch `7.16`, use `7.16` of this library or above, but
 not `8.0`.
 
+## Compatibility
+
+The Elasticsearch client is compatible with currently maintained PHP 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-PHP Branch | Supported |
+| --------------------- | ------------------------ | --------- |
+| main                  | main                     |           |
+| 8.x                   | 8.x                      | 8.x       |
+| 7.x                   | 7.x                      | 7.17      |
+
 ## Backward Incompatible Changes :boom:
 
 The 8.0.0 version of `elasticsearch-php` contains a new implementation compared
diff --git a/docs/overview.asciidoc b/docs/overview.asciidoc
index 9d1881170..cc03742c0 100644
--- a/docs/overview.asciidoc
+++ b/docs/overview.asciidoc
@@ -24,6 +24,31 @@ standard is a community effort that contains a set of interfaces defined by the
 PHP Framework Interop Group. For more information, refer to the 
 https://www.php-fig.org/psr/psr-7/[PSR 7 standard documentation].
 
+
+[discrete]
+[[version-compatibility]]
+=== {es} and PHP version Compatibility
+
+The {es} client is compatible with currently maintained PHP versions.
+
+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.
+
+|===
+| Elasticsearch Version | Elasticsearch-PHP Branch | Supported
+
+| main                  | main                     | 
+| 8.x                   | 8.x                      | 8.x
+| 7.x                   | 7.x                      | 7.17
+|===
+
+
 * <<breaking_changes>>
 
 include::breaking-changes.asciidoc[]
\ No newline at end of file