Node.js Stability Ratings

Stability ratings: 0-5

0 - Deprecated.  This feature is known to be problematic, and changes are
planned.  Do not rely on it.  Use of the feature may cause warnings.  Backwards
compatibility should not be expected.

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.

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.

3 - Stable.  The API has proven satisfactory, but cleanup in the underlying
code may cause minor changes.  Backwards-compatibility is guaranteed.

4 - API Frozen.  This API has been tested extensively in production and is
unlikely to ever have to change.

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.

@ry I'd read through the solaris stability indicators a few weeks ago, at your suggestion. They're ok, and they make sense for an OS. But there are a few aspects that make them suboptimal for node, and in trying to think of how to apply them to Node's API, I ended up at this simplified version.

1. There's frequent references to governing bodies, etc., which an operating system has a lot of. Node has none.
2. There are very few things in node that should be considered "not an interface". Basically just the output of util.inspect and console.trace, which we can put special language around. An operating system is often used by piping the string output of one program into another, so this is a much more relevant issue there.
3. Anything private should be obvious by virtue of not being exposed, being exposed only through process.binding, or having an underscore at the start of the name (which is such a common red-flag that most JavaScripters will be very fearful.) These interfaces should not be in the public-facing docs. (Documenting them elsewhere would be a good move to enable new contributors. Reading the code is best.)

That leaves Obsolete, Volatile, Uncommitted, and Committed, in order of least to most reliable.

I also want a way to shoo people away from making changes to, say, assert.js or module.js; these parts of the program are extremely sensitive, used internally, and have been behaving well for a long time. You should be able to rely on these with absolute confidence that nothing will change unless there is a very serious bug found, which is highly unlikely.

So, Obsolete, Volatile, Uncommitted, Committed, and Locked.

Then, I thought that there's a difference between API-locked and Code-locked. For example, module.js should just be considered hands-off except in extreme cases. On the other hand, while most of fs.js's API should be considered locked, and not open to further discussion, the code itself may need further cleanup or optimization as we use more of it in more platforms, and fixes that don't change the API are welcome. This is more than just a commitment to provide backwards-compatibility; it's a strong claim that we believe that backwards-compatibility will not ever even be an issue, because we're done changing the surface.

So, Obsolete, Volatile, Uncommitted, Committed, API Frozen, and Locked.

I then just changed the names to match what we actually use in discussions. For example, we refer to interfaces as "experimental", not as "volatile". ("Broken" should probably be called "deprecated", since that's the term we use internally. Updating gist.) "OK" sounds a bit more inviting than "Uncommitted", and since these interfaces are areas where we benefit from people using them, I don't want to scare them off too strongly. But maybe something a bit more risky-sounding would be good there.

Leaving us with:

Deprecated, Experimental, OK (?), Stable, API Frozen, and Locked.

I don't remember when I started thinking of them as a measure of Volatility rather than a measure of Stability, but having Stabiliity: <number> all over the docs might be a bit more encouraging on a subliminal level than Volatility: <number>. Reversing the order to reflect this.

I would go for "unsettled" or "unstable" instead of "ok" which to me is confusing.

Unstable is good. You're right, "ok" is kind of confusing.

Updated the list, and the language.