doc: clearer doc-only deprecations

BridgeAR · BridgeAR · commit 28a54cb83a5f · 2018-05-07T14:20:47.000+02:00
Explicitely mention that a documentation only deprecation does not always imply that it will be staged for deprecation in a future Node.js major release. It is mainly there to tell developers that a specific API should be avoided. PR-URL: #20381 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
@@ -416,14 +416,15 @@ longer be used.
 
 Node.js uses three Deprecation levels:
 
-* *Documentation-Only Deprecation* refers to elements of the Public API that are
-  being staged for deprecation in a future Node.js major release. An explicit
-  notice indicating the deprecated status is added to the API documentation
-  but no functional changes are implemented in the code. There will be no
-  runtime deprecation warnings emitted for such deprecations by default.
-  Documentation-only deprecations may trigger a runtime warning when Node.js
-  is started with the [`--pending-deprecation`][] flag or the
-  `NODE_PENDING_DEPRECATION=1` environment variable is set.
+* *Documentation-Only Deprecation* refers to elements of the Public API that
+  should be avoided by developers and that might be staged for a runtime
+  deprecation in a future Node.js major release. An explicit notice indicating
+  the deprecation status is added to the API documentation but no functional
+  changes are implemented in the code. By default there will be no deprecation
+  warnings emitted for such deprecations at runtime. Documentation-only
+  deprecations may trigger a runtime warning when Node.js is started with the
+  [`--pending-deprecation`][] flag or the `NODE_PENDING_DEPRECATION=1`
+  environment variable is set.
 
 * *Runtime Deprecation* refers to the use of process warnings emitted at
   runtime the first time that a deprecated API is used. A command-line
