Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [eclipse-dev] Best practices for provisional APIs

Provisional APIs are like real APIs in everything except the possibility
that they might change. Like real APIs, provisional APIs should be well
documented with all the Javadocs in place, well designed with names and
signatures that look real. If provisional APIs are treated seriously and
not changed gratuitously, they can serve a similar purpose of house bills
put through the process of becoming laws.

If I read the disclaimer and accept that I can be broken, I can use the new
function and provide necessary feedback to the developers. If I make myself
known to the developers, they will appreciate early adopters and give them
heads up when they need to make a breaking change. Sometimes this change
may be initiated by the early adopters themselves as a result of feedback.

I think that APIs that look real except for the disclaimer in Javadoc serve
a useful purpose as long as they don't stay in that stage forever (like a
student who never actually graduates :-).


Dejan Glozic, Ph.D.
Manager, Eclipse Development 1A
IBM Canada Ltd.
Tel. 905 413-2745  T/L 969-2745
Fax. 905 413-4850

             M@IBMCA                                                    To 
             Sent by:                  eclipse-dev@xxxxxxxxxxx             
             eclipse-dev-bounc                                          cc 
                                       Re: [eclipse-dev] Best practices    
             02/17/2006 10:11          for provisional APIs                
             Please respond to                                             
              mailing list of                                              
                the Eclipse                                                

There is a third type.  Code that is not intended to be used by others at
all.  That is the intended/historical meaning of "internal".  As such,
marking things internal with no indication that they are candidates for
being API may scare them off too much.  Often what we need for these
provisional API to become real is user involvement.  The data bindings are
a good example.  The UI team did not feel confident in the current shape
but yet would like people to look at the API and, to the extent that they
are willing to be broken going forward, use them and give feedback.   To
facilitate this, we need to communicate to them, which classes/methods are
candidates.  This also plays on Pascal's question about how to encourage
people to give that feedback. To facilitate that, it might be useful to
mention giving feedback as a sign to users that we are interested in their
input.  Giving a location for that feedback would be useful.

As for package naming, I have never been a fan of *.internal.provisional.*.
One or the other should be enough.  I would however encourage people to put
their provisional API classes together by domain in packages.  That is,
package it as if it were API so that people can understand the shape.

As for Javadoc, we have long had a standard template for marking things
experimental/provisional.  We should continue using that form (potentially
with a feedback statement) unless there are issues with it.


 Mike Wilson/Ottawa/IBM@IBMCA                                              
 Sent by:                                                               To 
 eclipse-dev-bounces@eclipse.            "General development mailing list 
 org                                     of the Eclipse project."          
 02/17/2006 09:01 AM                                                       
                                         Re: [eclipse-dev] Best practices  
       Please respond to                 for provisional APIs              
     "General development                                                  
  mailing list of the Eclipse                                              

I find the notion of provisional api to be basically just an oximoron. We
should have only two categories: API, and things that are internal because
they haven't yet stabilized/been validated enough to be API.


 Pascal Rapicault/Ottawa/IBM@IBMCA                                         
 Sent by:                                                                  
 02/17/06 08:44                                                         cc 
           Please respond to                     [eclipse-dev] Best        
  "General development mailing list of           practices for provisional 
         the Eclipse project."                   APIs                      


Should we adopt a consistent way to indicate provisional APIs across the
More specifically I'm wondering what are the rules for
- the package name. should the API be in the package where it would belong
if it was real API, or should it be in an internal package?
- the javadoc markup. should the javadoc say: experimental, provisional,
something else?

Aside from those questions, I propose to add to the javadoc an explicit
request for feedback from the users and explaining where this feedback
should be given (a mailing-list, a bug report, ...)

eclipse-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
eclipse-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
eclipse-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit

Back to the top