[eclipse-dev] Provisional API guidelines

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

There was discussion last week about
treatment of provisional APIs within the Eclipse project.  After several
rounds of discussions, we have arrived at these guidelines on provisional
APIs:

http://wiki.eclipse.org/index.php/Provisional_API_Guidelines

Note that these guidelines are intended
only for the Eclipse top-level project that produces the Eclipse SDK, and
are not targetted at other Eclipse Foundation projects.  The document
is a bit long, so here is the capsule summary for what to do with provisional
APIs at this point in the develoment of Eclipse 3.2 (after the API freeze):

 - All provisional APIs must be
in internal packages (org.eclipse.<componentName>.internal.*).
 - All provisional API packages
that are exported must be marked x-internal in the bundle manifest
 - Component teams can use the
"internal.provisional" package naming convention if they want
to separate provisional API from true internal code.  Whether this
convention is used is entirely up to each component.
 - Adding "provisional"
or "experimental" javadoc to code in an API package does not
make it provisional.  If it is public and in an API package after
the API freeze, it's API.