Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Linux Tools API Policy"
(→Requirements) |
(→Changes) |
||
| Line 47: | Line 47: | ||
New provisional API must be approved by the component or subproject lead. Due to the risk of stagnation or over-use, leads should ensure that the use is appropriate (e.g. is it ready for feedback? why can't it be declared as API instead?) and that we have a plan for evolution in the subsequent release. A bugzilla must be opened (using "[API]" in the Summary and "provisional" in the Whiteboard) to track the evolution of this code in the following release. | New provisional API must be approved by the component or subproject lead. Due to the risk of stagnation or over-use, leads should ensure that the use is appropriate (e.g. is it ready for feedback? why can't it be declared as API instead?) and that we have a plan for evolution in the subsequent release. A bugzilla must be opened (using "[API]" in the Summary and "provisional" in the Whiteboard) to track the evolution of this code in the following release. | ||
| − | Provisional API may evolve during the first milestones but it must be frozen by the regular API freeze date of a release and will not change for the remainder of the release and the corresponding maintenance releases. Exceptions must be approved by the | + | Provisional API may evolve during the first milestones but it must be frozen by the regular API freeze date of a release and will not change for the remainder of the release and the corresponding maintenance releases. Exceptions must be approved by the project lead. |
| − | Provisional API should not stagnate. It | + | Provisional API should not stagnate into Internal, but the guarantee is weaker than for Declared API. It undergo extensive change, or be removed in the following releases. No approval is necessary, but maintainers should notify the community of changes and make changes sparingly. |
= Internal API = | = Internal API = | ||
Revision as of 12:05, 17 May 2010
NOTE: This page is a work in progress and may evolve or radically change before it is finalized. Sections have been adapted from WTP_API_Policy
API availability has typically varied across projects in Linux Tools. With the recent push to standardize data collection and UI API's, however, the API policy will need to be stronger.
Contents
Declared API
Description
Declared API is API intended for outside use. Declared API is frozen at the time of release and will not be changed throughout the remainder of the release or in corresponding maintenance releases. The decision to create Declared API can be made by individual maintainers of Linux Tools projects, or by the PMC.
Demarcation
Declared API can be marked at the class or member level with the following javadoc comment:
* Declared API: This API is expected to be stable for the remainder of this release. * Please consult http://wiki.eclipse.log/Linux_Tools_API_Policy for more information.
Requirements
A project can only designate Declared API if this API is used by at least one other project. In some cases it is acceptable for the other project to be a different Linux Tools project.
Changes
Deprecation of Declared API can be carried out at the discretion of the project maintainer. However, a viable alternative or explanation why this feature is no longer possible/necessary must be provided as part of the API documentation. Declared API must be deprecated for more than 2 major releases before it can be removed.
Exceptions can be made, but they must be approved by the PMC and must be accompanied by a message to the community.
Provisional API
Description
Provisional API are Declared API that could not be frozen in time for release. It means that there is intent to eventually make this API Declared, but also that the API has known problems and may change significantly before the next release. Maintainers of provisional API make a commitment to keeping the API as stable as possible, but major changes (as determined by the discretion of the project maintainer or PMC) should be accompanied by a message to the community.
Demarcation
Provisional API can be marked at the class or member level with the following javadoc comment:
* WARNING: This class/interface is Provisional and may change. * Please consult http://wiki.eclipse.log/Linux_Tools_API_Policy for more information.
Requirements
Committers should avoid creating Provisional API in any package that would not be appropriate for the final Declared API. This includes package names that use words such as "internal" or "provisional". Labeling existing internal code as provisional is allowed in order to declare a greater degree of support to potential adopters, but committers should exercise care when using this option.
Changes
Provisional API become Declared when ready. API should not be left provisional for more than 2 major releases. Provisional API should only very rarely be removed or become internal.
New provisional API must be approved by the component or subproject lead. Due to the risk of stagnation or over-use, leads should ensure that the use is appropriate (e.g. is it ready for feedback? why can't it be declared as API instead?) and that we have a plan for evolution in the subsequent release. A bugzilla must be opened (using "[API]" in the Summary and "provisional" in the Whiteboard) to track the evolution of this code in the following release.
Provisional API may evolve during the first milestones but it must be frozen by the regular API freeze date of a release and will not change for the remainder of the release and the corresponding maintenance releases. Exceptions must be approved by the project lead.
Provisional API should not stagnate into Internal, but the guarantee is weaker than for Declared API. It undergo extensive change, or be removed in the following releases. No approval is necessary, but maintainers should notify the community of changes and make changes sparingly.
Internal API
Description
Internal API is API meant for internal use. Internal API may be changed at any time without notice.
Demarcation
Internal API can be directly marked by 'internal' in the package or extension point name, or tagged as 'x-internal' in a manifest file. Committers can also use the following javadoc comment:
* WARNING: Internal use only, this method may change without warning. * Please consult http://wiki.eclipse.log/Linux_Tools_API_Policy for more information.
Requirements
None. Anything can become internal, though transitions from Provisional and Declared API have restrictions.
It is safer to assume that any API not part of a Framework or not otherwise documented as Declared or Provisional falls by default under the Internal category. While these API can be used, there is no guarantee of stability. If any community members wish to use Internal API, they should inform the project maintainer. In many cases API are stable enough to be made Provisional or Declared if required.
Changes
Adopters who wish to make use of internal API should post an enhancement request on Bugzilla, and arrangements will be made to expose Internal API as Provisional API in the next major release if appropriate.
Frameworks
API defined as part of a framework project become Declared heading immediately following their first major release. Framework projects are unique insofar as they are created with the express purpose of making tools available to other projects, and so framework maintainers commit to maintaining stable API. The project maintainer can selectively and explicitly mark API as internal before a major release if so desired.
One example of a framework project within Linux Tools is the Profiling Framework, which contains API for launching and communicating with external tools as well as API for accessing other Eclipse capabilities. It is used by Eclipse Callgraph to create API for launching arbitrary SystemTap scripts.