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

[Boris Bokowski <Boris_Bokowski@xxxxxxxxxx>]

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