doc: add blurb about implications of ABI stability

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.
 

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