From 5490114ea96e6b60b0c2b8de607096765b3e2fbc Mon Sep 17 00:00:00 2001
From: Tomas Della Vedova <delvedor@users.noreply.github.com>
Date: Tue, 10 Nov 2020 17:46:33 +0100
Subject: [PATCH] Added node.js support doc (#1346)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
---
 README.md                  | 28 +++++++++++++--
 docs/installation.asciidoc | 74 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 99 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 8ceb50b81..b28a72cfe 100644
--- a/README.md
+++ b/README.md
@@ -26,9 +26,33 @@ The official Node.js client for Elasticsearch.
 npm install @elastic/elasticsearch
 ```
 
-### Compatibility
+### Node.js support
 
-The minimum supported version of Node.js is `v8`.
+NOTE: The minimum supported version of Node.js is `v8`.
+
+The client versioning follows the Elastc Stack versioning, this means that
+major, minor, and patch releases are done following a precise schedule that
+often does not coincide with the [Node.js release](https://nodejs.org/en/about/releases/) times.
+
+To avoid support insecure and unsupported versions of Node.js, the
+client **will drop the support of EOL versions of Node.js between minor releases**.
+Typically, as soon as a Node.js version goes into EOL, the client will continue
+to support that version for at least another minor release. If you are using the client
+with a version of Node.js that will be unsupported soon, you will see a warning
+in your logs (the client will start logging the warning with two minors in advance).
+
+Unless you are **always** using a supported version of Node.js, 
+we recommend defining the client dependency in your
+`package.json` with the `~` instead of `^`. In this way, you will lock the
+dependency on the minor release and not the major. (for example, `~7.10.0` instead
+of `^7.10.0`).
+
+| Node.js Version | Node.js EOL date | End of support         |
+| --------------- |------------------| ---------------------- |
+| `8.x`           | `December 2019`  | `7.11` (early 2021)    |       
+| `10.x`          | `Apri 2021`      | `7.12` (mid 2021)      |        
+
+### Compatibility
 
 The library is compatible with all Elasticsearch versions since 5.x, and you should use the same major version of the Elasticsearch instance that you are using.
 
diff --git a/docs/installation.asciidoc b/docs/installation.asciidoc
index fc71de537..d9621ced1 100644
--- a/docs/installation.asciidoc
+++ b/docs/installation.asciidoc
@@ -18,4 +18,76 @@ npm install @elastic/elasticsearch@<major>
 ----
 
 To learn more about the supported major versions, please refer to the 
-<<js-compatibility-matrix>>.
\ No newline at end of file
+<<js-compatibility-matrix>>.
+
+[discrete]
+[[nodejs-support]]
+=== Node.js support
+
+NOTE: The minimum supported version of Node.js is `v8`.
+
+The client versioning follows the {stack} versioning, this means that
+major, minor, and patch releases are done following a precise schedule that
+often does not coincide with the https://nodejs.org/en/about/releases/[Node.js release] times.
+
+To avoid support insecure and unsupported versions of Node.js, the
+client *will drop the support of EOL versions of Node.js between minor releases*.
+Typically, as soon as a Node.js version goes into EOL, the client will continue
+to support that version for at least another minor release. If you are using the client
+with a version of Node.js that will be unsupported soon, you will see a warning
+in your logs (the client will start logging the warning with two minors in advance).
+
+Unless you are *always* using a supported version of Node.js, 
+we recommend defining the client dependency in your
+`package.json` with the `~` instead of `^`. In this way, you will lock the
+dependency on the minor release and not the major. (for example, `~7.10.0` instead
+of `^7.10.0`).
+
+[%header,cols=3*]
+|===
+|Node.js Version
+|Node.js EOL date
+|End of support
+
+|`8.x`
+|December 2019
+|`7.11` (early 2021)
+
+|`10.x`
+|April 2021
+|`7.12` (mid 2021)
+|===
+
+[discrete]
+[[js-compatibility-matrix]]
+=== Compatibility matrix
+
+The library is compatible with all {es} versions since 5.x. We recommend you to
+use the same major version of the client as the {es} instance that you are
+using.
+
+[%header,cols=2*]
+|===
+|{es} Version
+|Client Version
+
+|`master`
+|`master`
+
+|`7.x`
+|`7.x`
+
+|`6.x`
+|`6.x`
+
+|`5.x`
+|`5.x`
+|===
+
+
+[discrete]
+==== Browser
+
+WARNING: There is no official support for the browser environment. It exposes
+your {es} instance to everyone, which could lead to security issues. We
+recommend you to write a lightweight proxy that uses this client instead.