Provisional API Guidelines

From Eclipsepedia

Revision as of 10:53, 23 February 2006 by Johna (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Eclipse quality APIs don't appear fully formed out of nowhere. All APIs undergo a development process, passing through many phases from initial embroyonic forms to real battle-hardened APIs with guarantees of long term support. It is important that API clients understand the state of the APIs in any given build of Eclipse. These guidelines set out how to indicate APIs that are still under development and subject to change. Although the Eclipse quality guidelines distinguish between several forms of transient APIs, this document will refer to all such APIs as simply provisional APIs.

The development cycle for each major and minor Eclipse project release has a milestone designated as the API freeze. The rules for development and treatment of APIs are different for the periods before and after this point, so this document outlines guidelines for both phases of the development cycle.

Definition of terms used in this document:

API package 
Any package that does not contain the segment "internal". (see Naming Conventions for details)
non-API package 
Any Java package containing the segment "internal".
API element 
A Java class, interface, method, or field in an API package

<div id="pre_freeze"/>

Provisional APIs prior to the API freeze

Prior to the API freeze, any class, interface, method or field in an API package.