From 6a6448fe798e190119390c75783f2d5e7a987333 Mon Sep 17 00:00:00 2001 From: Zach Brisson <162374237+ZachBrisson-Elastic@users.noreply.github.com> Date: Wed, 16 Apr 2025 10:58:42 -0400 Subject: [PATCH 1/5] Update index.md Appended the client compatibility matrix to call out the 9.x client compatibility for 9.x release. --- docs/reference/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/index.md b/docs/reference/index.md index 99282dec2..2cdce9ee9 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -61,6 +61,7 @@ Language clients are forward compatible; meaning that the clients support commun | Elasticsearch version | elasticsearch-py branch | Supported | | --- | --- | --- | | main | main | | +| 9.x | 9.x | 9.x | | 8.x | 8.x | 8.x | | 7.x | 7.x | 7.17 | From 37b63f3914e30dca3f428f9a742fe80255a4be4b Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Wed, 16 Apr 2025 19:10:41 +0400 Subject: [PATCH 2/5] Update compatibility matrix wording --- README.md | 23 ++++++++--------------- docs/reference/index.md | 16 ++++++++-------- 2 files changed, 16 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 20b72407d..30c7ec34c 100644 --- a/README.md +++ b/README.md @@ -63,21 +63,14 @@ 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 | - +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 across minor versions with default distributions and without guarantees made. To upgrade to a new major version, you first need to upgrade Elasticsearch, then the Python Elasticsearch client. + +| Elasticsearch version | elasticsearch-py branch | +| --- | --- | +| main | main | +| 9.x | 9.x | +| 9.x | 8.x | +| 8.x | 8.x | If you have a need to have multiple versions installed at the same time older versions are also released as ``elasticsearch7`` and ``elasticsearch8``. diff --git a/docs/reference/index.md b/docs/reference/index.md index 2cdce9ee9..df79d8570 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -56,13 +56,13 @@ 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. - -| Elasticsearch version | elasticsearch-py branch | Supported | -| --- | --- | --- | -| main | main | | -| 9.x | 9.x | 9.x | -| 8.x | 8.x | 8.x | -| 7.x | 7.x | 7.17 | +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 across minor versions with default distributions and without guarantees made. To upgrade to a new major version, you first need to upgrade Elasticsearch, then the Python Elasticsearch client. + +| Elasticsearch version | elasticsearch-py branch | +| --- | --- | +| main | main | +| 9.x | 9.x | +| 9.x | 8.x | +| 8.x | 8.x | If you have a need to have multiple versions installed at the same time older versions are also released as `elasticsearch7` and `elasticsearch8`. From da604d13c6bd675b4a081a40be523b9ace625f93 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 17 Apr 2025 13:21:26 +0400 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/reference/index.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/reference/index.md b/docs/reference/index.md index df79d8570..709a45366 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -56,7 +56,9 @@ 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 across minor versions with default distributions and without guarantees made. To upgrade to a new major version, you first need to upgrade Elasticsearch, then the Python Elasticsearch client. +Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of {{es}} without breaking. + +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. | Elasticsearch version | elasticsearch-py branch | | --- | --- | @@ -65,4 +67,10 @@ Language clients are forward compatible; meaning that the clients support commun | 9.x | 8.x | | 8.x | 8.x | -If you have a need to have multiple versions installed at the same time older versions are also released as `elasticsearch7` and `elasticsearch8`. +{{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`. From b1dbeb22db6a6fd3f8c1fefdea22da1ed04f5d41 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 17 Apr 2025 13:25:46 +0400 Subject: [PATCH 4/5] Adapt index.md changes to README.md --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 30c7ec34c..85c37945a 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,9 @@ of the getting started documentation. ## 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 across minor versions with default distributions and without guarantees made. To upgrade to a new major version, you first need to upgrade Elasticsearch, then the Python Elasticsearch client. +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 | | --- | --- | @@ -72,8 +74,12 @@ Language clients are forward compatible; meaning that the clients support commun | 9.x | 8.x | | 8.x | 8.x | -If you have a need to have multiple versions installed at the same time older -versions are also released as ``elasticsearch7`` and ``elasticsearch8``. +Elasticsearch language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees. + +> [!NOTE] +> 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 From d1bc0bd0e591b3c177637e817fec16d9e41de4f8 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 17 Apr 2025 13:29:13 +0400 Subject: [PATCH 5/5] Switch from NOTE to TIP --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 85c37945a..11d1b8259 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ Compatibility does not imply full feature parity. New Elasticsearch features are Elasticsearch language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees. -> [!NOTE] +> [!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`.