From a448c8b779f1d3b34e2ab9511d88c8b4702f10b8 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] 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.

PR-URL: https://github.com/nodejs/node/pull/22508
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
---
 doc/api/addons.md |  4 ++++
 doc/api/n-api.md  | 30 ++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/doc/api/addons.md b/doc/api/addons.md
index 9ea0a6b6446ce4..bba4820ca9c084 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 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).
+
 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 a21d1f7ad70bff..4f27d8c55223d6 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -42,6 +42,36 @@ 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,
+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_version.h>
+    #include <node_object_wrap.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 libraries 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