From 75b45a3bf5a45addeecbeb0dd17680d9e27484b9 Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof <gabriel.schulhof@intel.com>
Date: Fri, 24 Aug 2018 13:11:50 -0400
Subject: [PATCH 1/3] doc: add blurb about implications of ABI stability

Mention that ABI stability can be achieved only by linking to ABI-
stable parts of Node.js and to other libraries which are ABI-stable.
---
 doc/api/addons.md |  4 ++++
 doc/api/n-api.md  | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/doc/api/addons.md b/doc/api/addons.md
index 9ea0a6b6446ce4..de4a87aa45bee1 100644
--- a/doc/api/addons.md
+++ b/doc/api/addons.md
@@ -367,6 +367,10 @@ set of APIs that are used by the native code. Instead of using the V8
 or [Native Abstractions for Node.js][] APIs, the functions available
 in the N-API are used.
 
+Creating and maintaining an add-on that benefits from the ABI stability
+provided by N-API carries with it certain
+[implementation considerations](n-api.html#n_api_implications_of_abi_stability).
+
 To use N-API in the above "Hello world" example, replace the content of
 `hello.cc` with the following. All other instructions remain the same.
 
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index c047715395d742..f7bb07685d2ed4 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -42,6 +42,39 @@ for the N-API C based functions exported by Node.js. These wrappers are not
 part of N-API, nor will they be maintained as part of Node.js. One such
 example is: [node-addon-api](https://github.com/nodejs/node-addon-api).
 
+## Implications of ABI Stability
+
+Although N-API provides an ABI stability guarantee, other parts of Node.js do
+not, and any external libraries used from the addon may not. In particular,
+neither of the following Node.js APIs provides an ABI stability guarantee:
+* the Node.js C++ APIs available via any of
+    ```C++
+    #include <node_buffer.h>
+    #include <node_context_data.h>
+    #include <node_contextify.h>
+    #include <node_mutex.h>
+    #include <node_object_wrap.h>
+    #include <node_perf_common.h>
+    #include <node_platform.h>
+    #include <node_version.h>
+    ```
+* the libuv APIs which are also included with Node.js and available via
+    ```C++
+    #include <uv.h>
+    ```
+* the V8 API available via
+    ```C++
+    #include <v8.h>
+    ```
+
+Thus, for an addon to remain ABI-compatible across Node.js major versions, it
+must make use exclusively of N-API by restricting itself to using
+```C
+#include <node_api.h>
+```
+and by checking, for all external library that it uses, that the external
+library makes ABI stability guarantees similar to N-API.
+
 ## Usage
 
 In order to use the N-API functions, include the file

From 78bf7abc419f5bdfa214e630e818ed246fe6e3c3 Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Fri, 24 Aug 2018 18:33:36 -0700
Subject: [PATCH 2/3] squash! add-on -> addon

---
 doc/api/addons.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/addons.md b/doc/api/addons.md
index de4a87aa45bee1..bba4820ca9c084 100644
--- a/doc/api/addons.md
+++ b/doc/api/addons.md
@@ -367,7 +367,7 @@ set of APIs that are used by the native code. Instead of using the V8
 or [Native Abstractions for Node.js][] APIs, the functions available
 in the N-API are used.
 
-Creating and maintaining an add-on that benefits from the ABI stability
+Creating and maintaining an addon that benefits from the ABI stability
 provided by N-API carries with it certain
 [implementation considerations](n-api.html#n_api_implications_of_abi_stability).
 

From 7ba8ae4cf19c43659e90c0e1040c238f17e75586 Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof <gabriel.schulhof@intel.com>
Date: Mon, 27 Aug 2018 16:59:56 -0400
Subject: [PATCH 3/3] squash! address review comments

---
 doc/api/n-api.md | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index f7bb07685d2ed4..fd3b56e2b04e8a 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -46,17 +46,14 @@ example is: [node-addon-api](https://github.com/nodejs/node-addon-api).
 
 Although N-API provides an ABI stability guarantee, other parts of Node.js do
 not, and any external libraries used from the addon may not. In particular,
-neither of the following Node.js APIs provides an ABI stability guarantee:
+none of the following APIs provide an ABI stability guarantee across major
+versions:
 * the Node.js C++ APIs available via any of
     ```C++
+    #include <node.h>
     #include <node_buffer.h>
-    #include <node_context_data.h>
-    #include <node_contextify.h>
-    #include <node_mutex.h>
-    #include <node_object_wrap.h>
-    #include <node_perf_common.h>
-    #include <node_platform.h>
     #include <node_version.h>
+    #include <node_object_wrap.h>
     ```
 * the libuv APIs which are also included with Node.js and available via
     ```C++
@@ -72,7 +69,7 @@ must make use exclusively of N-API by restricting itself to using
 ```C
 #include <node_api.h>
 ```
-and by checking, for all external library that it uses, that the external
+and by checking, for all external libraries that it uses, that the external
 library makes ABI stability guarantees similar to N-API.
 
 ## Usage