Re: [eclipse-dev] Provisional API guidelines

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

The guidelines describe two defining
characteristics of an API package:

  1) The package name doesn't contain
the word "internal"
  2) The package is exported unconditionally
by the plug-in's bundle manifest (not x-internal or x-friends)

We should make sure both are true for
API packages in the SDK.  Admittedly there are some special cases,
such as the OSGi framework adapter, that don't nicely fit into either the
"API" or "internal" category.  In this case, they
are an SPI (service provider interface) for a special kind of client.  They
are marked x-internal, and no javadoc is produced for them.  Another
exception is packages whose namespace we don't have control over, such
as org.osgi.* and org.apache.*. In these cases x-internal is used to indicate
which packages are not API.  However, cases like this are the exception
rather than the rule.

Wassim Melhem/Toronto/IBM@IBMCA
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

27/02/2006 06:41 PM

Please respond to
"General development mailing list of the Eclipse project."

To	"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
cc
Subject	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'
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


_______________________________________________
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