Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update stability index #943

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/api/assert.markdown
Original file line number Diff line number Diff line change
@@ -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')`.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/buffer.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/child_process.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/cluster.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/console.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# console

Stability: 4 - API Frozen
Stability: 2 - Stable

* {Object}

Expand Down
3 changes: 1 addition & 2 deletions doc/api/crypto.markdown
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
2 changes: 1 addition & 1 deletion doc/api/debugger.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Debugger

Stability: 3 - Stable
Stability: 2 - Stable

<!-- type=misc -->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/dgram.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# UDP / Datagram Sockets

Stability: 3 - Stable
Stability: 2 - Stable

<!-- name=dgram -->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/dns.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# DNS

Stability: 3 - Stable
Stability: 2 - Stable

Use `require('dns')` to access this module.

Expand Down
30 changes: 8 additions & 22 deletions doc/api/documentation.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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.
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If "Backwards-compatibility is guaranteed." is removed, how can my npm modules declare which versions of the built-in modules like url and path they are compatible with?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the above:

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's not even an answer to the only question in my comment.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The whole idea is that backwards compatibility is guaranteed by semver, stability levels don't really matter

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do I, as a module author, assert this semver in my package.json? There is no engines.iojs field I'm aware of.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is currently no mechanism for this outside of feature detection. A breaking change in a stable API must demonstrate enough value to justify the breakage – that bar is very high.

## JSON Output
Expand Down
2 changes: 1 addition & 1 deletion doc/api/domain.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Domain

Stability: 2 - Unstable
Stability: 0 - Deprecated
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not yet?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By deprecated we mean "DON'T USE THIS!" :)


**This module is pending deprecation**. Once a replacement API has been
finalized, this module will be fully deprecated. Most end users should
Expand Down
2 changes: 1 addition & 1 deletion doc/api/events.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Events

Stability: 4 - API Frozen
Stability: 2 - Stable

<!--type=module-->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/fs.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# File System

Stability: 3 - Stable
Stability: 2 - Stable

<!--name=fs-->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/http.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# HTTP

Stability: 3 - Stable
Stability: 2 - Stable

To use the HTTP server and client one must `require('http')`.

Expand Down
2 changes: 1 addition & 1 deletion doc/api/https.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/modules.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Modules

Stability: 5 - Locked
Stability: 3 - Locked

<!--name=module-->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/net.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/os.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# OS

Stability: 4 - API Frozen
Stability: 2 - Stable

Provides a few basic operating-system related utility functions.

Expand Down
2 changes: 1 addition & 1 deletion doc/api/path.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/punycode.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/querystring.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Query String

Stability: 3 - Stable
Stability: 2 - Stable

<!--name=querystring-->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/readline.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/repl.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/smalloc.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Smalloc

Stability: 1 - Experimental
Stability: 2 - Stable

## Class: smalloc

Expand Down
2 changes: 1 addition & 1 deletion doc/api/stream.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/string_decoder.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/timers.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/tls.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# TLS (SSL)

Stability: 3 - Stable
Stability: 2 - Stable

Use `require('tls')` to access this module.

Expand Down
2 changes: 1 addition & 1 deletion doc/api/tty.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/url.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/util.markdown
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/v8.markdown
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/api/vm.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Executing JavaScript

Stability: 3 - Stable
Stability: 2 - Stable

<!--name=vm-->

Expand Down
2 changes: 1 addition & 1 deletion doc/api/zlib.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Zlib

Stability: 3 - Stable
Stability: 2 - Stable

You can access this module with:

Expand Down
10 changes: 1 addition & 9 deletions doc/api_assets/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down