Documentation stability levels: Difference between revisions

From Open-Xchange
No edit summary
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<div class="title">Documentation stability levels</div>
Documentation for OX components is subject to change since the products are improved continuously. To know how reliable a piece of documentation is, we have introduced the following levels to rate our own documentation.
In  creating this we were inspired by the [http://nodejs.org/api/documentation.html#documentation_stability_index node.js stability index].
__TOC__
== Deprecated ==
== Deprecated ==
This feature is known to be problematic, and changes are
This feature is known to be problematic, and changes are
Line 10: Line 19:
or be removed in future versions.  Please try it out and provide feedback.
or be removed in future versions.  Please try it out and provide feedback.


Changes will not be announced.
Changes will not be announced. Using the ''watch'' function to stay updated may help, but we do not guarantee to update the documentation concurrent with code changes.


== Unstable ==
== Unstable ==
The API is in the process of settling, but has not yet had
The API is in the process of settling, but has not yet had
sufficient real-world testing to be considered stable. Backwards-compatibility
sufficient real-world testing to be considered stable.  
will be maintained if reasonable.


Changes will not be announced. We recommend using the ''watch'' function for the given page to keep updated.
Changes will not be announced. We recommend using the ''watch'' function for the given page to stay updated.


== Stable ==
== Stable ==
The API has proven satisfactory, but cleanup in the underlying
The API has proven satisfactory, but cleanup in the underlying
code may cause minor changes. Backwards-compatibility is attempted really hard.
code may cause minor changes. Backwards-compatibility
will be maintained if reasonable.


Changes will be announced in the release notes.
Incompatible changes will be announced in the release notes.


== Frozen ==
== Frozen ==
This API has been tested extensively in production and is
This API has been tested extensively in production and is
unlikely to ever have to change. Backwards-compatibility is guaranteed.
unlikely to ever have to change. If they do occur anyway, changes will be announced in the release notes two major releases in advance.
 
Changes will be announced in the release notes, parallel versions will be maintained for two major releases.
 


In  creating this we were inspired by the [http://nodejs.org/api/documentation.html#documentation_stability_index node.js stability index]. Thanks a lot, you rock.
[[Category:Meta]]

Latest revision as of 15:14, 25 April 2013

Documentation stability levels

Documentation for OX components is subject to change since the products are improved continuously. To know how reliable a piece of documentation is, we have introduced the following levels to rate our own documentation.

In creating this we were inspired by the node.js stability index.


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.

Changes will not be announced.

Experimental

This feature was introduced recently, and may change or be removed in future versions. Please try it out and provide feedback.

Changes will not be announced. Using the watch function to stay updated may help, but we do not guarantee to update the documentation concurrent with code changes.

Unstable

The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable.

Changes will not be announced. We recommend using the watch function for the given page to stay updated.

Stable

The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility will be maintained if reasonable.

Incompatible changes will be announced in the release notes.

Frozen

This API has been tested extensively in production and is unlikely to ever have to change. If they do occur anyway, changes will be announced in the release notes two major releases in advance.