[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
Re: [eclipse-dev] How to deal with API leakage?
|
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