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 0901a25..787f159 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 e7bbe19..8bbcae7 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 71ffe98..518d61c 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 85ab523..6a923b4 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 6cd2488..f9b4f8f 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 e82c5e0..03687c7 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 e20730f..9b33eb7 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 92bf993..d370712 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 024ffec..a30af87 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 24f3d2c..2cb03c8 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 ee66e41..56e8f06 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 7170454..2febc2f 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 9b824b1..14d24bf 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 49ad016..c4af8f4 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 2e97e56..3c82af6 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 3cd7175..920da77 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 c98a0a8..f55bc19 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 7f3605e..9202c74 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 d353559..6b10d1c 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 9448706..f633e3c 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 e907c4e..e16e6e7 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 f2ae5ea..d3600fd 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 91e2050..1ca020f 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 19c18dc..80b4ce9 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 e8dc938..2d6e1da 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 b8a6252..4189923 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 201fb04..7df7264 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 ea9b6cd..5b81067 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 bad059c..60012f3 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 e4b2320..51fdb7e 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 ad71451..dcd7532 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 29f0de8..adced82 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 b145324..254aa36 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 923f49d..a9ceb31 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 d5c5aa9..e816ce5 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; } -- 2.7.4