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

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.

PaScaL



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

Boris



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





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.


PaScaL



                                                                         
Boris                                                                    
Bokowski/Ottawa/IBM@IBMCA                                                
Sent by:                                                               To
eclipse-dev-bounces@eclipse.                 "General development mailing
org                                          list of the Eclipse          
                                             project."                    
                                             <eclipse-dev@xxxxxxxxxxx>    
02/17/2006 11:03 AM                                                    cc
                                                                         
                                                                  Subject
      Please respond to                      RE: [eclipse-dev] Best      
    "General development                     practices for provisional    
 mailing list of the Eclipse                 APIs                        
          project."                                                      
                                                                         
                                                                         
                                                                         
                                                                         
                                                                         
                                                                         





+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.

Boris





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






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,

-t


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
that.)


_______________________________________________________________________
Notice:  This email message, together with any attachments, may contain
information  of  BEA Systems,  Inc.,  its subsidiaries  and  affiliated
entities,  that may be confidential,  proprietary,  copyrighted  and/or
legally privileged, and is intended solely for the use of the individual
or entity named in this message. If you are not the intended recipient,
and have received this message in error, please immediately return this
by email and then delete it.
_______________________________________________
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
_______________________________________________
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

Back to the top