netbeans.apache.org/src/content/wiki/API_Stability.adoc - netbeans-website - Git at Google

 //
 //     Licensed to the Apache Software Foundation (ASF) under one
 //     or more contributor license agreements.  See the NOTICE file
 //     distributed with this work for additional information
 //     regarding copyright ownership.  The ASF licenses this file
 //     to you under the Apache License, Version 2.0 (the
 //     "License"); you may not use this file except in compliance
 //     with the License.  You may obtain a copy of the License at
 //
 //       http://www.apache.org/licenses/LICENSE-2.0
 //
 //     Unless required by applicable law or agreed to in writing,
 //     software distributed under the License is distributed on an
 //     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 //     KIND, either express or implied.  See the License for the
 //     specific language governing permissions and limitations
 //     under the License.
 //

 = API Stability
 :jbake-type: wiki
 :jbake-tags: wiki, devfaq, needsreview
 :markup-in-source: verbatim,quotes,macros
 :jbake-status: published
 :syntax: true
 :description: NetBeans API Stability
 :icons: font
 :source-highlighter: pygments
 :toc: left
 :toc-title:
 :experimental:

 [[categories]]
 In order to clearly communicate what stage an xref:API_Design.adoc[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
 xref:API_Stability.adoc[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]]
 == Private

 *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]]
 == Friend

 *Friend* xref:API_Design.adoc[API] is used for features accessible to
 specific components in the system, that help to overcome the lack of a real
 stable xref:API_Design.adoc[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.


 [[devel]]
 == Devel

 *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]]
 == Stable

 *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 xref:API_Design.adoc[API]).


 [[official]]
 == Official

 *Official* are <<Stable,stable>> ones and also packaged into one of NetBeans
 official namespaces: `org.netbeans.api` or `org.netbeans.spi` or `org.openide`.
 By packaging a contract into this package (and making it part of a release) one
 notifies others that the contract is
 xref:APIDevelopment.adoc#Official_APIs_Restrictions[stable - with all the
 consequence] (except the conditional support for
 xref:APIDevelopment.adoc#Support_for_Early_Adoption[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_of_Investments,preservation>>
 section).


 [[third_party]]
 == Third Party

 *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]]
 == Standard

 *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 link:http://www.jcp.org[JSRs]). The standard is
 expected to not change frequently.


 [[deprecated]]
 == Deprecated

 *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
 to `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).

 [NOTE]
 ====
 The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.

 This page was exported from link:http://wiki.netbeans.org/API%20Stability[http://wiki.netbeans.org/API%20Stability] , 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.
 ====
	//
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.
	//

	= API Stability
	:jbake-type: wiki
	:jbake-tags: wiki, devfaq, needsreview
	:markup-in-source: verbatim,quotes,macros
	:jbake-status: published
	:syntax: true
	:description: NetBeans API Stability
	:icons: font
	:source-highlighter: pygments
	:toc: left
	:toc-title:
	:experimental:

	[[categories]]
	In order to clearly communicate what stage an xref:API_Design.adoc[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
	xref:API_Stability.adoc[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]]
	== Private

	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]]
	== Friend

	Friend xref:API_Design.adoc[API] is used for features accessible to
	specific components in the system, that help to overcome the lack of a real
	stable xref:API_Design.adoc[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.


	[[devel]]
	== Devel

	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]]
	== Stable

	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 xref:API_Design.adoc[API]).


	[[official]]
	== Official

	Official are <<Stable,stable>> ones and also packaged into one of NetBeans
	official namespaces: `org.netbeans.api` or `org.netbeans.spi` or `org.openide`.
	By packaging a contract into this package (and making it part of a release) one
	notifies others that the contract is
	xref:APIDevelopment.adoc#Official_APIs_Restrictions[stable - with all the
	consequence] (except the conditional support for
	xref:APIDevelopment.adoc#Support_for_Early_Adoption[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_of_Investments,preservation>>
	section).


	[[third_party]]
	== Third Party

	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]]
	== Standard

	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 link:http://www.jcp.org[JSRs]). The standard is
	expected to not change frequently.


	[[deprecated]]
	== Deprecated

	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
	to `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).

	[NOTE]
	====
	The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.

	This page was exported from link:http://wiki.netbeans.org/API%20Stability[http://wiki.netbeans.org/API%20Stability] , 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.
	====