API status: Difference between revisions

From Open-Xchange
(A preview for John, who might want to weigh in on the wording)
 
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div class="title">Feature stability levels</div>
<div class="title">API Status</div>
At Open-Xchange we are continuously improving our products. Most of the time the
changes we make will have no side effects on existing installations and 3rd
party software integration. However, sometimes fixing a bug or adding a new
feature requires changes to the existing API that are not always backwards
compatible.


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.
To help you understand the impact of these changes we have defined the following
 
API status list. This page describes each level and indicates how information
In  creating this we were inspired by the [http://nodejs.org/api/documentation.html#documentation_stability_index node.js stability index].
about changes to documented features is communicated.


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 ==
API features can be categorized as follows.
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.
== In Development ==
{{Stability-experimental}}


== Upcoming ==
This feature is currently being developed by Open-Xchange. If this is a customer
This feature is currently being developed and may change or be removed in future versions. Please try it out and provide feedback.
request the customer requesting the change will provide feedback. On occasion
Open-Xchange may solicit input from a wider audience in order to optimize
feature development for the widest possible audience. Due to the low overhead of
making changes at this stage feedback is more likely to be integrated into the
feature than at other status levels.


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.
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 this cannot be guaranteed.


== New ==
== New ==
This feature came out just recently and is in the process of settling, but has not yet had
{{Stability-unstable}}
sufficient real-world testing to be considered stable.  
 
This feature was recently released, is fully tested and considered stable but is in the process of settling. Based on customer experience across a diverse range
of production environments it is possible that further changes may be necessary.
To indicate this we have defined a separate level from Stable.


Changes will not be announced. We recommend using the ''watch'' function for the given page to stay updated.
This feature is documented. 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.
{{Stability-stable}}


Incompatible changes will be announced in the release notes.
The feature is considered stable and is fully documented. However it is possible
that cleanup in the underlying code may cause minor changes.
Backwards-compatibility will be maintained if possible.
 
Changes that are not backwards compatible will be announced in the release
notes.


== 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.
{{Stability-frozen}}
 
This API has been tested extensively in production and is unlikely to be
changed. If changes do occur they will be announced in the release notes two
major releases in advance.
 
== Deprecated ==
{{Stability-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]]
[[Category:AppSuite]]

Latest revision as of 14:04, 7 August 2013

API Status

At Open-Xchange we are continuously improving our products. Most of the time the changes we make will have no side effects on existing installations and 3rd party software integration. However, sometimes fixing a bug or adding a new feature requires changes to the existing API that are not always backwards compatible.

To help you understand the impact of these changes we have defined the following API status list. This page describes each level and indicates how information about changes to documented features is communicated.

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

API features can be categorized as follows.

In Development

API status: In Development

This feature is currently being developed by Open-Xchange. If this is a customer request the customer requesting the change will provide feedback. On occasion Open-Xchange may solicit input from a wider audience in order to optimize feature development for the widest possible audience. Due to the low overhead of making changes at this stage feedback is more likely to be integrated into the feature than at other status 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 this cannot be guaranteed.

New

API status: New

This feature was recently released, is fully tested and considered stable but is in the process of settling. Based on customer experience across a diverse range of production environments it is possible that further changes may be necessary. To indicate this we have defined a separate level from Stable.

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

Stable

API status: Stable

The feature is considered stable and is fully documented. However it is possible that cleanup in the underlying code may cause minor changes. Backwards-compatibility will be maintained if possible.

Changes that are not backwards compatible will be announced in the release notes.

Frozen

API status: Frozen

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

Deprecated

API status: 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.