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 -- Lessons learned in WTP


The problem at hand is what we do with APIs that are still provisional at the time 3.2 is released.  These are APIs that we are not yet ready to commit to, but want to make available to early adopters so they can give feedback on it. You are correct that any APIs @since 3.2 in builds prior to the 3.2 release should also be treated as subject to change, whether they say so in the API or not.


Sent by: eclipse-dev-bounces@xxxxxxxxxxx

20/02/2006 07:32 PM

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

"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
RE: [eclipse-dev] Best practices for provisional APIs --        Lessons        learned in WTP


A quick observation on this subject. IF you are using an API there is a perfectly good javadoc mechanism for flagging it as provisional: @since

If you use any of this API marked with @since 3.2, you should be prepared for it to *possibly* change, as the build is - by definition - provisional (at least until declared frozen, although even then...). If it is API (provisional or not), it should be in the public package where it is intended. How can you have an API freeze if said API is definitely going to move? Back to my hole...

- jed.

David M Williams <david_williams@xxxxxxxxxx>
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

18/02/2006 03:05 PM
Please respond to "General development mailing list of the Eclipse project."

       To:        "General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>



       Subject:        RE: [eclipse-dev] Best practices for provisional APIs -- Lessons        learned in WTP

Wow, the more things change, the more they stay the same. :)  

The wtp-dev mailing-list archives contain a similar discussion thread from a year ago, and against the advice of some senior eclipse leaders,
      we decided to use the word "provisional", in some cases, and have since decided not to, as a practice.

Our findings were:

      Most clients (adopters) did not like the aspect of "automatically have to change their code", even if just to rename packages (as Tim W has mentioned in this thread).

              I think from their, the adopter client's perspective, they may use the provisional API's, may even make some comments, suggestions, etc., then they
              move on to other things, and even if the provisional API becomes official API .. they may not be migrating "in step" with the changes, but perhaps months later, and by that
              point, even a package rename seems complicated and seldom goes perfectly and the "experts" in that area are likely busy with other things.
              And, even though we righteously told them "its good for you" since it forces you to re-examine your use and make sure its correct ... .that doesn't
              go over well with teams that are just trying to make products on shoe-string budgets and don't mind the risk of a few subtle changes.
              This out-of-step aspect is even worse if there are several clients of the provisional API, and they are not all migrating at the same time.

      Relatedly, but originating from developers perspective, changing the package names from one stage to another (just to change "classification")
              causes the CVS history to get "lost" (that is, hard to do compares to past versions).

      Lastly ... and this is the one that surprised me ... its amazing how many clients (adopters) do not care about provisional stuff -- and more, they simply don't want to hear about it.
              Again, this is from their perspective of building products, and they either want API or not. And, the "provisional" classification
              (whether in package name or not) just confuses them. We've already seen some variance even in this short mailing list
              discussion that implies "provisional" means different things to different people -- from one extreme of it has to mean "nearly API" but might change a little in future ...
              to the other extreme of "not intended to be eternally an internal implementation and may change a great deal in future". So, there's no substitute to having concrete

              clients lined up to begin with, and they should not need the 'provisional' cue in package names.

      Hence, our practice is: if the provisional API is planned to be API "in the next release", use the long-term-intended name, JavaDoc well the exact "state" of the API,
              what kind of changes are likely, which are not, etc. AND, use the x-internal:=true markup.
              If it is not yet planned when it will become API, then leave as 'internal' (in name and markup, and assume it never will be API  :)

      Myself, I love shades of gray for design and incremental development .. but most do not, from a software business point of view.
              My guess is that it will be 5 years before there is much demand or capacity for an x-internalness=low-risk | medium-risk | high-risk, and
              I predict Randy's fears will come true ... that "discouraged access" will number in the thousands for some large teams, and be comparable to the
              thousands of deprecated warnings that some large teams acquire over cramped releases.


Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

02/17/2006 08:54 PM

Please respond to
"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>

"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
RE: [eclipse-dev] Best practices for provisional APIs

One thing that has been missing from this discussion is the use of x-internal.  The *covention* of naming packages as *.internal.* is useful but in the end not sufficient.  There are a number of cases where it is not feasible to base the package names on how a particular plugin needs to expose that code.  For example, code acquired from another party, SPI or downward API, ...  The x-internal mechanism allows you to mark up a package, regardless of its name, in the manifest of the bundle.  External uses of packages marked as x-internal:=true will trigger a compiler warning/error (according to your compiler prefs) so you get immediate and complete feedback on your use of non-API.  This mechanism gives us complete freedom now to use whatever package names we want and still have the API indications given to consumers.

Note that it is not just a tooling play.   The resolver and runtime also follow the directives and control visibility accordingly (if running in strict mode).  

In any event, 3.1 (and 3.2) includes x-internal markup for all the api and it is that markup that should be the most accurate indicator of API ness.  


Pascal Rapicault/Ottawa/IBM@IBMCA
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

02/17/2006 06:28 PM

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

"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>, eclipse-dev-bounces@xxxxxxxxxxx
RE: [eclipse-dev] Best practices for provisional APIs

When I answered I knew you would eventually say something like that and I had an answer prepared :-)

I think this is an ovesight of the versioning story and it should be changed to explain that even though as an author of a provisional API you should think of it as real API, all changes to it should be viewed
as new API causing the 2nd segment of the version to be changed.

Boris Bokowski/Ottawa/IBM@IBMCA
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

02/17/2006 03:35 PM

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

"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
RE: [eclipse-dev] Best practices for provisional APIs

Good idea, but doesn't this break the rules for versioning plug-ins:

"Each segment captures a different intent:
 the major segment indicates breakage in the API
 the minor segment indicates "externally visible" changes
 the service segment indicates bug fixes and the change of development
 stream (the semantics attached to development stream is new to this
 proposal, see below)
 the qualifier segment indicates a particular build"

I thought that by definition, non-internal packages form the API.
Therefore, if I am making changes that break the API contract, the major
segment has to be incremented.

Regarding the "strong disruption":   Like Randy and Jeff, I think it is
useful to be able to mark some of your internal classes as proposed API, to
make it easier for clients to distinguish between packages with internal
implementation classes and packages that they should look at and comment
on.  If it is too difficult to collapse "internal.provisional" to just
"provisional", that's not a big deal, I can live with long package names.


        IBM@IBMCA                                                  To
        Sent by:                  "General development mailing list  
        eclipse-dev-bounc         of the Eclipse project."            
        es@xxxxxxxxxxx            <eclipse-dev@xxxxxxxxxxx>          
                                  "General development mailing list  
        17/02/2006 14:33          of the Eclipse project."            
        Please respond to                                     Subject
            "General              RE: [eclipse-dev] Best practices    
           development            for provisional APIs                
         mailing list of                                              
           the Eclipse                                                

Adopting what you are proposing would actually represent a strong
distruption from what is now current practice in the eclipse ecosystem and
would likely confused consummers.

Personnaly I'm in agreement with Dejan. As an API author I should treat it
like API and it should be in the namespace where it will eventually
belongs. However as a consummer I should make sure that I'm treating it as
an internal package, meaning that I need to express my requirements on the
provider of the provisional package very tightly (for example, if I used
jface.databinding I would say [1.0.0, 1.1.0) since I can't be sure of what
will be the API in 1.1). Doing so, will protect me from changes in the API.


Sent by:                                                               To
eclipse-dev-bounces@eclipse.                 "General development mailing
org                                          list of the Eclipse          
02/17/2006 11:03 AM                                                    cc
  Please respond to                      RE: [eclipse-dev] Best      
"General development                     practices for provisional    
mailing list of the Eclipse                 APIs                        

+1 for using just provisional for unpublished "API", internal for
implementation classes, and neither provisional nor internal for real API.

If this requires changes to the tools, or change to the codified Eclipse
Development Process, then why not?

I do think, however, that it is problematic if you don't change the package
name once an API is published.  There are two strong reasons against
putting non-API in a public package: First, you cannot be sure that clients
have to recompile to keep using the API.  As a result, when evolving the
not-quite-public API, you now have to worry about binary compatibility
rather than just source compatibility.  Second, and this may only apply to
Platform or the SDK: you would have to increment the major segment of the
plug-in version number in the case where you find out that the API needs to
change.  Now consider the ripple effect of bumping the major version number
of, say, org.eclipse.jface, and it becomes clear why putting (however
tagged) non-API in public packages is a bad idea.

If you are lucky and the provisional "API" stays unchanged when publishing
it, you would only have to change the minor segment of the version number,
and all you require clients to do is to do an organize imports and update
their version number and dependencies accordingly.


       "Tim Wagner"
       Sent by:                                                   To
       eclipse-dev-bounc         "General development mailing list
       es@xxxxxxxxxxx            of the Eclipse project."
       17/02/2006 10:34
                                 RE: [eclipse-dev] Best practices
       Please respond to         for provisional APIs
        mailing list of
          the Eclipse

One objection that?s been raised to ?internal.provisional? in the past is
that provisional APIs are APIs you hope *not* to change, and that naming
convention guarantees you need to change at least that much. FWIW,


From: eclipse-dev-bounces@xxxxxxxxxxx
[mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Ed Burnette
Sent: Friday, February 17, 2006 7:31 AM
To: General development mailing list of the Eclipse project.
Subject: RE: [eclipse-dev] Best practices for provisional APIs

From: eclipse-dev-bounces@xxxxxxxxxxx
[mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Randy Hudson

I would prefer just ".provisional" or ".experimental" prefix in the
package name. Clients are more likely to look at the API, which is the
whole point to releasing it in its "unpolished" state.  Oh .... and it's
easier to type.

No, that doesn't work because Eclipse now has all these access warnings set
up that key off of ".internal". I know that's configurable but...

Jeff, would it be good enough to encourage usage by calling them .internal
but having a comment in the Javadoc that says something to the effect of
"Yeah, it's internal but we expect it to be api soon, so please try it and
comment on bug xxx". And then users can deliberately add those packages to
the access whitelist. To me this is orthogonal to what is done for things
you know are going to be API but are iffy during the milestones, you don't
use .internal but you put a "this is experimental" comment in the javadoc.

(If you really wanted to get fancy you could have a new javadoc tag like
'@visibility x' where 'x' was your confidence level in how stable it was.
Maybe something on whether it was intended to be extended too. The compiler
could adjust diagnostics based on that. But I'm not actually suggesting

Back to the top