Re: [eclipse-dev] How to deal with API leakage?

[Darin Wright <Darin_Wright@xxxxxxxxxx>]

We found a similar case in debug (before API tooling existed).

        https://bugs.eclipse.org/bugs/show_bug.cgi?id=132055

In our case, we were leaking a return type on a protected metohd. To 
maintain binary compatibility we left the method in, but deprecated it 
(and added an appropriate priavte method to replace it).

To be safe and guarentee binary compatibility, I think we should *not* 
remove API methods to fix leaks (unless this is new API added in 3.4). I 
think we should deprecate and add a porting guide entry. Clients should 
already have discouraged access warnings if they are using such a method.

In the case of an interface that is to be implemented by clients, this is 
less desirable (since they *must* declare the method). However,  you could 
also add a @noreference tag to the method.

Summary of my suggestion:
* leave the method 
* deprecate and add @noreference tag
* add a porting guide entry describing the change

Darin 



Boris Bokowski/Ottawa/IBM@IBMCA 
Sent by: eclipse-dev-bounces@xxxxxxxxxxx
04/16/2008 03:30 PM
Please respond to
"General development mailing list of the Eclipse project." 
<eclipse-dev@xxxxxxxxxxx>


To
eclipse-dev@xxxxxxxxxxx
cc

Subject
[eclipse-dev] How to deal with API leakage?







Platform UI has released "API" in 3.3 that leaked internal types. The API
is unusable for clients unless they reference non-API types.

How do we want to deal with cases like this in general? Do we consider 
this
API that needs to be maintained forever, even if it cannot be used in an
API-clean way? Or do we allow breaking changes in order to turn it into
useful API, with an entry in the porting guide?

Our particular case (see
https://bugs.eclipse.org/bugs/show_bug.cgi?id=224390) is even more
complicated. Early in the 3.4 cycle, a bug report came in (supposedly from
the first adopter of that API), pointing out that the API was not usable.
We fixed the API, assuming that breaking changes are allowed in a case 
like
this. Now the API tools don't agree with that and we have a binary
incompatible change reported against one of our bundles. Our options at
this point are: 1. leave the API in its current state - this would break
clients that went ahead and used the 3.3 API despite they had to reference
internal types; or 2. revert the change to get rid of the incompatibility
with 3.3 - this would break the "good client" who reported the API 
problem,
and it would break them at a very late stage.

I would like to hear what others think about the general case, and our
particular case. (The PMC's opinion would be useful too.)

Boris

_______________________________________________
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