Note: These pages are being reviewed.
In order to clearly communicate what stage an API is in, whether it is still being evolved, whether it is expected to ever be real API or whether it is stable and ready to use, let us introduce a system of stability clasification for APIs. The aim is to give the code authors way how to communicate their intention with particular feature and others to find out such information.
Private is a category for features that are accessible but are not intended for use outside of their component (module). Such features are subject to change with every release and depending on them is risky and should be avoided.
Friend API is used for features accessible to specific components in the system, that help to overcome the lack of a real stable API, but are intended only for use between these friend components and nobody else. Often friend components are developed by the same group of people. A change to this contract can be done every release, but owners of those friend components must be notified in advance. No one else should depend on such features - the author of this API does not have the intent to create a general purpose API.
Under development is a name for a contract that is expected to become a stable API, but that has not yet been finished. The current state serves as a proof of concept, and others are encourage to try it and comment on a dedicated mailing list. Incompatible changes may be done between releases, but should be rare, not radical and properly announced on the mailing list.
Stable interfaces are those that have received a final state and the maintainers are ready to support it forever and never change them incompatibly. The "forever" and "never" should not be taken as absolute: It is possible to change the contract, but only in major versions and only after a careful considerations and in cases where it is imperative that a change be made. Stable contracts should preserve the investments of those entering into them (users of an API).
Official are stable ones and also packaged into one of NetBeans
By packaging a contract into this package (and making it part of a release) one
notifies others that the contract is
stable - with all the
consequence (except the conditional support for
early adoptions - such
modules has code base name that ends with with /0). Also, the impact of
possible incompatible changes to official API should be minimized by
providing compatibility bridges and keeping binary compatibility even when
source one is droped (see the preservation
Third party interfaces are provided by other parties that do not follow the NetBeans rules and thus are hard to classify. It is prefered not to expose such interfaces as part of own contracts, in order to insulate users of NetBeans APIs from unexpected changes made in the imported interfaces.
Standard is similar to the third party classification. Also provided by someone out of NetBeans, but by someone expected to evolve the interface in compatible way (for example JSRs). The standard is expected to not change frequently.
Deprecated. After a while, nearly every API, regardless of what state it
is, becomes obsoleted. Usually a new, better support for the same task has been
developed which replaces the old API. In such case, mark the old API
deprecated. A previously stable API that changed its stability
deprecated shall be supported for reasonable amount of time (a
release) to communicate to users that they shall migrate from it to the new
replacement. After that time the API can be removed from the product, while
trying to preserve it for old clients by making it available in alternative
ways (e. g. autoupdate centers).
The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
This page was exported from http://wiki.netbeans.org/API Stability , that was last modified by NetBeans user Jtulach on 2012-01-07T22:32:21Z.
This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.