Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [eclipse-dev] Provisional API guidelines

The definition that an API package is "Any package that does not contain
the segment  'internal'" may have become too simplistic over time and may
need to be revised.

It's not so black and white in the SDK.

Here is some gray:

Take a look at the org.eclipse.osgi plug-in.  It contains many a package
that are marked as internal and yet they do not contain the 'internal'
That does not make them API, does it?


             BM@IBMCA                                                   To 
             Sent by:                  eclipse-dev@xxxxxxxxxxx             
             eclipse-dev-bounc                                          cc 
                                       [eclipse-dev] Provisional API       
             02/27/2006 03:47          guidelines                          
             Please respond to                                             
              mailing list of                                              
                the Eclipse                                                

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:

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
 - 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.
eclipse-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit

Back to the top