From cf0306cd71e9283b385593749e4f757df6e52d33 Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Tue, 24 Feb 2015 16:15:26 -0800 Subject: [PATCH] doc: update stability index This simplifies the stability index to 4 levels: 0 - deprecated 1 - experimental / feature-flagged 2 - stable 3 - locked Domains has been downgraded to deprecated, assert has been downgraded to stable. Timers and Module remain locked. All other APIs are now stable. PR-URL: https://github.com/iojs/io.js/pull/943 Fixes: https://github.com/iojs/io.js/issues/930 Reviewed-By: Colin Ihrig Reviewed-By: Jeremiah Senkpiel Reviewed-By: Vladimir Kurchatkin --- doc/api/assert.markdown | 2 +- doc/api/buffer.markdown | 2 +- doc/api/child_process.markdown | 2 +- doc/api/cluster.markdown | 2 +- doc/api/console.markdown | 2 +- doc/api/crypto.markdown | 3 +-- doc/api/debugger.markdown | 2 +- doc/api/dgram.markdown | 2 +- doc/api/dns.markdown | 2 +- doc/api/documentation.markdown | 30 ++++++++---------------------- doc/api/domain.markdown | 2 +- doc/api/events.markdown | 2 +- doc/api/fs.markdown | 2 +- doc/api/http.markdown | 2 +- doc/api/https.markdown | 2 +- doc/api/modules.markdown | 2 +- doc/api/net.markdown | 2 +- doc/api/os.markdown | 2 +- doc/api/path.markdown | 2 +- doc/api/punycode.markdown | 2 +- doc/api/querystring.markdown | 2 +- doc/api/readline.markdown | 2 +- doc/api/repl.markdown | 2 +- doc/api/smalloc.markdown | 2 +- doc/api/stream.markdown | 2 +- doc/api/string_decoder.markdown | 2 +- doc/api/timers.markdown | 2 +- doc/api/tls.markdown | 2 +- doc/api/tty.markdown | 2 +- doc/api/url.markdown | 2 +- doc/api/util.markdown | 2 +- doc/api/v8.markdown | 2 +- doc/api/vm.markdown | 2 +- doc/api/zlib.markdown | 2 +- doc/api_assets/style.css | 10 +--------- 35 files changed, 42 insertions(+), 65 deletions(-) diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index 0901a250bc..787f159e58 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -1,6 +1,6 @@ # Assert - Stability: 5 - Locked + Stability: 2 - Stable This module is used for writing unit tests for your applications, you can access it with `require('assert')`. diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index e7bbe1980c..8bbcae73bf 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -1,6 +1,6 @@ # Buffer - Stability: 3 - Stable + Stability: 2 - Stable Pure JavaScript is Unicode friendly but not nice to binary data. When dealing with TCP streams or the file system, it's necessary to handle octet diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index 71ffe98c0a..518d61c0d5 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -1,6 +1,6 @@ # Child Process - Stability: 3 - Stable + Stability: 2 - Stable io.js provides a tri-directional `popen(3)` facility through the `child_process` module. diff --git a/doc/api/cluster.markdown b/doc/api/cluster.markdown index 85ab523af2..6a923b45cf 100644 --- a/doc/api/cluster.markdown +++ b/doc/api/cluster.markdown @@ -1,6 +1,6 @@ # Cluster - Stability: 2 - Unstable + Stability: 2 - Stable A single instance of io.js runs in a single thread. To take advantage of multi-core systems the user will sometimes want to launch a cluster of io.js diff --git a/doc/api/console.markdown b/doc/api/console.markdown index 6cd2488370..f9b4f8ffa4 100644 --- a/doc/api/console.markdown +++ b/doc/api/console.markdown @@ -1,6 +1,6 @@ # console - Stability: 4 - API Frozen + Stability: 2 - Stable * {Object} diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index e82c5e0ef0..03687c75c3 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -1,7 +1,6 @@ # Crypto - Stability: 2 - Unstable; API changes are being discussed for - future versions. Breaking changes will be minimized. See below. + Stability: 2 - Stable Use `require('crypto')` to access this module. diff --git a/doc/api/debugger.markdown b/doc/api/debugger.markdown index e20730fa41..9b33eb7d4f 100644 --- a/doc/api/debugger.markdown +++ b/doc/api/debugger.markdown @@ -1,6 +1,6 @@ # Debugger - Stability: 3 - Stable + Stability: 2 - Stable diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 92bf993d48..d370712789 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -1,6 +1,6 @@ # UDP / Datagram Sockets - Stability: 3 - Stable + Stability: 2 - Stable diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index 024ffec213..a30af870e5 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -1,6 +1,6 @@ # DNS - Stability: 3 - Stable + Stability: 2 - Stable Use `require('dns')` to access this module. diff --git a/doc/api/documentation.markdown b/doc/api/documentation.markdown index 24f3d2ce59..2cb03c8f8a 100644 --- a/doc/api/documentation.markdown +++ b/doc/api/documentation.markdown @@ -42,34 +42,20 @@ compatibility should not be expected. ``` Stability: 1 - Experimental -This feature was introduced recently, and may change -or be removed in future versions. Please try it out and provide feedback. -If it addresses a use-case that is important to you, tell the node core team. +This feature is subject to change, and is gated by a command line flag. +It may change or be removed in future versions. ``` ``` -Stability: 2 - Unstable -The API is in the process of settling, but has not yet had -sufficient real-world testing to be considered stable. Backwards-compatibility -will be maintained if reasonable. +Stability: 2 - Stable +The API has proven satisfactory. Compatibility with the npm ecosystem +is a high priority, and will not be broken unless absolutely necessary. ``` ``` -Stability: 3 - Stable -The API has proven satisfactory, but cleanup in the underlying -code may cause minor changes. Backwards-compatibility is guaranteed. -``` - -``` -Stability: 4 - API Frozen -This API has been tested extensively in production and is -unlikely to ever have to change. -``` - -``` -Stability: 5 - Locked -Unless serious bugs are found, this code will not ever -change. Please do not suggest changes in this area; they will be refused. +Stability: 3 - Locked +Only fixes related to security, performance, or bug fixes will be accepted. +Please do not suggest API changes in this area; they will be refused. ``` ## JSON Output diff --git a/doc/api/domain.markdown b/doc/api/domain.markdown index ee66e41563..56e8f0650a 100644 --- a/doc/api/domain.markdown +++ b/doc/api/domain.markdown @@ -1,6 +1,6 @@ # Domain - Stability: 2 - Unstable + Stability: 0 - Deprecated **This module is pending deprecation**. Once a replacement API has been finalized, this module will be fully deprecated. Most end users should diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 71704547ad..2febc2f991 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -1,6 +1,6 @@ # Events - Stability: 4 - API Frozen + Stability: 2 - Stable diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 9b824b105c..14d24bfe5a 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -1,6 +1,6 @@ # File System - Stability: 3 - Stable + Stability: 2 - Stable diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 49ad0160ec..c4af8f407c 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -1,6 +1,6 @@ # HTTP - Stability: 3 - Stable + Stability: 2 - Stable To use the HTTP server and client one must `require('http')`. diff --git a/doc/api/https.markdown b/doc/api/https.markdown index 2e97e56ab6..3c82af61c2 100644 --- a/doc/api/https.markdown +++ b/doc/api/https.markdown @@ -1,6 +1,6 @@ # HTTPS - Stability: 3 - Stable + Stability: 2 - Stable HTTPS is the HTTP protocol over TLS/SSL. In io.js this is implemented as a separate module. diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index 3cd7175975..920da77651 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -1,6 +1,6 @@ # Modules - Stability: 5 - Locked + Stability: 3 - Locked diff --git a/doc/api/net.markdown b/doc/api/net.markdown index c98a0a8dc5..f55bc194d2 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -1,6 +1,6 @@ # net - Stability: 3 - Stable + Stability: 2 - Stable The `net` module provides you with an asynchronous network wrapper. It contains methods for creating both servers and clients (called streams). You can include diff --git a/doc/api/os.markdown b/doc/api/os.markdown index 7f3605e064..9202c74914 100644 --- a/doc/api/os.markdown +++ b/doc/api/os.markdown @@ -1,6 +1,6 @@ # OS - Stability: 4 - API Frozen + Stability: 2 - Stable Provides a few basic operating-system related utility functions. diff --git a/doc/api/path.markdown b/doc/api/path.markdown index d353559bd8..6b10d1c1bb 100644 --- a/doc/api/path.markdown +++ b/doc/api/path.markdown @@ -1,6 +1,6 @@ # Path - Stability: 3 - Stable + Stability: 2 - Stable This module contains utilities for handling and transforming file paths. Almost all these methods perform only string transformations. diff --git a/doc/api/punycode.markdown b/doc/api/punycode.markdown index 944870677a..f633e3ccd1 100644 --- a/doc/api/punycode.markdown +++ b/doc/api/punycode.markdown @@ -1,6 +1,6 @@ # punycode - Stability: 3 - Stable + Stability: 2 - Stable [Punycode.js](https://mths.be/punycode) is bundled with io.js v1.0.0+ and Node.js v0.6.2+. Use `require('punycode')` to access it. (To use it with diff --git a/doc/api/querystring.markdown b/doc/api/querystring.markdown index e907c4e7d5..e16e6e7d77 100644 --- a/doc/api/querystring.markdown +++ b/doc/api/querystring.markdown @@ -1,6 +1,6 @@ # Query String - Stability: 3 - Stable + Stability: 2 - Stable diff --git a/doc/api/readline.markdown b/doc/api/readline.markdown index f2ae5ea73a..d3600fd49d 100644 --- a/doc/api/readline.markdown +++ b/doc/api/readline.markdown @@ -1,6 +1,6 @@ # Readline - Stability: 2 - Unstable + Stability: 2 - Stable To use this module, do `require('readline')`. Readline allows reading of a stream (such as `process.stdin`) on a line-by-line basis. diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown index 91e20506a9..1ca020f035 100644 --- a/doc/api/repl.markdown +++ b/doc/api/repl.markdown @@ -1,6 +1,6 @@ # REPL - Stability: 3 - Stable + Stability: 2 - Stable A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily includable in other programs. The REPL provides a way to interactively diff --git a/doc/api/smalloc.markdown b/doc/api/smalloc.markdown index 19c18dc89e..80b4ce921d 100644 --- a/doc/api/smalloc.markdown +++ b/doc/api/smalloc.markdown @@ -1,6 +1,6 @@ # Smalloc - Stability: 1 - Experimental + Stability: 2 - Stable ## Class: smalloc diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index e8dc938b4a..2d6e1da846 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -1,6 +1,6 @@ # Stream - Stability: 2 - Unstable + Stability: 2 - Stable A stream is an abstract interface implemented by various objects in io.js. For example a [request to an HTTP diff --git a/doc/api/string_decoder.markdown b/doc/api/string_decoder.markdown index b8a6252d66..4189923b97 100644 --- a/doc/api/string_decoder.markdown +++ b/doc/api/string_decoder.markdown @@ -1,6 +1,6 @@ # StringDecoder - Stability: 3 - Stable + Stability: 2 - Stable To use this module, do `require('string_decoder')`. StringDecoder decodes a buffer to a string. It is a simple interface to `buffer.toString()` but provides diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown index 201fb04ec2..7df72641c6 100644 --- a/doc/api/timers.markdown +++ b/doc/api/timers.markdown @@ -1,6 +1,6 @@ # Timers - Stability: 5 - Locked + Stability: 3 - Locked All of the timer functions are globals. You do not need to `require()` this module in order to use them. diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index ea9b6cd08a..5b81067b3a 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -1,6 +1,6 @@ # TLS (SSL) - Stability: 3 - Stable + Stability: 2 - Stable Use `require('tls')` to access this module. diff --git a/doc/api/tty.markdown b/doc/api/tty.markdown index bad059cdbb..60012f3063 100644 --- a/doc/api/tty.markdown +++ b/doc/api/tty.markdown @@ -1,6 +1,6 @@ # TTY - Stability: 2 - Unstable + Stability: 2 - Stable The `tty` module houses the `tty.ReadStream` and `tty.WriteStream` classes. In most cases, you will not need to use this module directly. diff --git a/doc/api/url.markdown b/doc/api/url.markdown index e4b2320f46..51fdb7ec3d 100644 --- a/doc/api/url.markdown +++ b/doc/api/url.markdown @@ -1,6 +1,6 @@ # URL - Stability: 3 - Stable + Stability: 2 - Stable This module has utilities for URL resolution and parsing. Call `require('url')` to use it. diff --git a/doc/api/util.markdown b/doc/api/util.markdown index ad714517b8..dcd7532a71 100644 --- a/doc/api/util.markdown +++ b/doc/api/util.markdown @@ -1,6 +1,6 @@ # util - Stability: 4 - API Frozen + Stability: 2 - Stable These functions are in the module `'util'`. Use `require('util')` to access them. diff --git a/doc/api/v8.markdown b/doc/api/v8.markdown index 29f0de8e0d..adced82685 100644 --- a/doc/api/v8.markdown +++ b/doc/api/v8.markdown @@ -1,6 +1,6 @@ # V8 - Stability: 1 - Experimental + Stability: 2 - Stable This module exposes events and interfaces specific to the version of [V8][] built with io.js. These interfaces are subject to change by upstream and are diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown index b1453249ec..254aa36e25 100644 --- a/doc/api/vm.markdown +++ b/doc/api/vm.markdown @@ -1,6 +1,6 @@ # Executing JavaScript - Stability: 3 - Stable + Stability: 2 - Stable diff --git a/doc/api/zlib.markdown b/doc/api/zlib.markdown index 923f49da1a..a9ceb314ed 100644 --- a/doc/api/zlib.markdown +++ b/doc/api/zlib.markdown @@ -1,6 +1,6 @@ # Zlib - Stability: 3 - Stable + Stability: 2 - Stable You can access this module with: diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index d5c5aa9e55..e816ce5fbb 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -88,18 +88,10 @@ code a:hover { } .api_stability_2 { - background-color: #FFA000; + background-color: #4EBA0F; } .api_stability_3 { - background-color: #AEC516; -} - -.api_stability_4 { - background-color: #009431; -} - -.api_stability_5 { background-color: #0084B6; }