Difference between revisions of "API status"

(A preview for John, who might want to weigh in on the wording)
 
Line 1: Line 1:
 
<div class="title">Feature stability levels</div>
 
<div class="title">Feature stability levels</div>
  
Documentation for OX components is subject to change since the products are improved continuously. To let you know how reliable a documented feature is, we have introduced the following levels to ratethem.
+
Open-Xchange products are continuously improved. Most of the time, these improvements result in changes, which have no side-effects on existing installations and integrations with 3rd party software. Unfortunatly, sometimes, fixing a bug or adding a new feature requires changing existing features in a way that breaks backward compatibility.
  
In creating this we were inspired by the [http://nodejs.org/api/documentation.html#documentation_stability_index node.js stability index].
+
To help you stay informed about such changes, and to help you decide, when to deploy them, we mark documentation pages with a stability level. This page defines what each stability level means and where you should look for information about current and upcoming changes to the documented feature.
 +
 
 +
In creating these levels we were inspired by the [http://nodejs.org/api/documentation.html#documentation_stability_index node.js stability index].
  
  
 
__TOC__
 
__TOC__
  
== Deprecated ==
+
== In development ==
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.
+
This feature is currently being developed and may change or be removed in future versions. Please try it out and provide feedback. Due to the low overhead of making changes at this stage, your feedback is more likely to be integrated into the feature, than in the other stability levels.
  
Changes will not be announced.
+
Changes will not be announced. Using the ''watch'' function to stay updated may help. We will try to update the documentation concurrently with code changes, but cannot guarantee it.
 
 
== Upcoming ==
 
This feature is currently being developed 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.
 
  
 
== New ==
 
== New ==
This feature came out just recently and is in the process of settling, but has not yet had
+
This feature came out just recently and is in the process of settling. Since changes are more likely due to feedback from first real-world experiences, this is a separate level from Stable.
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.
 
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 code may cause minor changes. Backwards-compatibility will be maintained if reasonable.
+
The feature 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.
 
Incompatible changes will be announced in the release notes.
Line 31: Line 27:
 
== Frozen ==
 
== 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.
 
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.
 +
 +
== Deprecated ==
 +
This feature is known to be problematic, and changes or even removal 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.
  
 
[[Category:Meta]]
 
[[Category:Meta]]

Revision as of 16:08, 30 July 2013

Feature stability levels

Open-Xchange products are continuously improved. Most of the time, these improvements result in changes, which have no side-effects on existing installations and integrations with 3rd party software. Unfortunatly, sometimes, fixing a bug or adding a new feature requires changing existing features in a way that breaks backward compatibility.

To help you stay informed about such changes, and to help you decide, when to deploy them, we mark documentation pages with a stability level. This page defines what each stability level means and where you should look for information about current and upcoming changes to the documented feature.

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


In development

This feature is currently being developed and may change or be removed in future versions. Please try it out and provide feedback. Due to the low overhead of making changes at this stage, your feedback is more likely to be integrated into the feature, than in the other stability levels.

Changes will not be announced. Using the watch function to stay updated may help. We will try to update the documentation concurrently with code changes, but cannot guarantee it.

New

This feature came out just recently and is in the process of settling. Since changes are more likely due to feedback from first real-world experiences, this is a separate level from Stable.

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

Stable

The feature 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.

Deprecated

This feature is known to be problematic, and changes or even removal 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.