Re: [eclipse-dev] Provisional API guidelines

[Wassim Melhem <wassimm@xxxxxxxxxx>]

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'
segment.
That does not make them API, does it?


Wassim.




                                                                           
             John                                                          
             Arthorne/Ottawa/I                                             
             BM@IBMCA                                                   To 
             Sent by:                  eclipse-dev@xxxxxxxxxxx             
             eclipse-dev-bounc                                          cc 
             es@xxxxxxxxxxx                                                
                                                                   Subject 
                                       [eclipse-dev] Provisional API       
             02/27/2006 03:47          guidelines                          
             PM                                                            
                                                                           
                                                                           
             Please respond to                                             
                 "General                                                  
                development                                                
              mailing list of                                              
                the Eclipse                                                
                 project."                                                 
                                                                           
                                                                           





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.
 _______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev