Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat

What we (the Eclipse Platform team) call API is defined in this article:

In particular, packages with "internal", "examples", or "tests" is not considered API.

APIs are interfaces with _specified_ and _supported_ behaviour. Specified in the sense that they come with Javadoc that explains how the APIs are supposed to work, and supported in the sense that we will fix bugs, and honour the API specification.

Sometimes, the term "API contract" is used. But when you think about it, you will realize that you can only call something a contract if you know the parties involved in that contract. In a sense, the Platform APIs are more accurately described as a promise, because the Platform team, unilaterally, makes promises about the interfaces of their software components, namely that those interfaces will be supported, and only be evolved in a way that is binary compatible.

The situation becomes a little more complex when you start to think about software development over time, as opposed to just looking at a particular point in time. The promises as described above only apply to releases of our software. During the development cycle, all bets are off (i.e. interfaces may change at any time, week-to-week binary compatibility is not an issue). Of course, we try to do what makes sense from an engineering standpoint and don't change interfaces willy-nilly - so in practice, interfaces don't change that much during development. In fact, towards the end of a development cycle, we have what we call the "API freeze", usually M6, after which we exert tight control over which aspects of our interfaces are still allowed to change.

We have tried to avoid calling interfaces "API" when they do not come with specified and supported behaviour, in an attempt to avoid confusion. If you say "provisional API", you probably mean "specified, but not supported in the same way as real API", which is somewhat nebulous in the absence of a more concrete definition.

One potential definition is the following: use the name segment "internal.provisional" in packages with specified interfaces, when the component owners are not making support promises, or at best very little promises, such as they will not remove the interfaces in maintenance releases. Of course, these interfaces are not considered API in the strong sense.

Another potential definition would be if "provisional API" was not a unilateral promise, but a bilateral contract between known parties. In this case, it would become possible to negotiate the terms, for example, for how long will this interface be supported? Will it be evolved in a binary compatible way? Etc. (Note that the terms would only apply to those parties who explicitly entered into that contract - no free rides.)

It is important to realize that both potential definitions are only practical if the provider of the interfaces, and the consumer of the interfaces, have coordinated release cycles. The reason for this is that once you allow contracts like this, or less strong promises, provider components and consumer components cannot work together unless what they think of as their interface is the same. In other words, consumers would have to specify tighter version bounds for the bundles they depend on.

To sum up, you can "play these games" within a product, or perhaps between components that participate in the annual Eclipse release train. But for outside consumers, or commercial products built using Eclipse components, I don't see how interfaces that do not fall under the strong definition of "API" would be useful, or even usable.


Inactive hide details for "Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>"Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>

          "Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>
          Sent by: eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx

          10/21/2008 07:59 AM

          Please respond to
          E4 developer list <eclipse-incubator-e4-dev@xxxxxxxxxxx>


"E4 developer list" <eclipse-incubator-e4-dev@xxxxxxxxxxx>



RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat

Hello Krzysztof,

[2] After the API freeze, there is really no such thing as "provisional API". Either it is complete and committed platform API, or it is internal code.
Hm... I know this passage and agree that it is not in line with my current
thinking. Perhaps Boris, John or McQ could explain? For me, it seems

OK to have provisional API live in "internal" packages even across multiple
Just assuming that some provisional API was proposed and just didn't get
ready in time. This can't be a reason for never ever working on promoting

it in the future? The passage cited does not seem logical, and I'm wondering
if it could be rewritten for clarification.

[2] Technically, a provisional API can change arbitrarily or be removed at any time without notice.
Yes, I agree that this doesn't sound friendly for provisional API adopters at
all, and does not help encouraging early adoption. I think that we should

consider more helpful policies, such as
    • Provisional API can be removed at any milestone build, provided that
      it has been marked @deprecated in the previous milestone build.
Discussing such policies for provisional API (making a recommendation for
all Eclipse projects to adopt them) would be a good topic for the Architecture

Council. The goal of the discussion should be increasing early adoption and
feedback for provisional API. I'd just like to get some initial feedback on this
idea before I file a bug on the Architecture Council component (well in fact
anybody can file such a bug).

Note the public package in the provisional API. It is contradictory to the [2]

I assume that in the cited table, the "public" means that the packages are
exported and publicly visible (which is recommended for EVERY package
including those that have an "internal" segment in their package name. In
this light, this isn't a contradiction.

new API is released as provisional in release X and then hardened into platform APIs in release X+1.

Well that also seems too blindly following a principle. The API is ready when
it is ready and shouldn't be promoted just because it's old. A better description
should be
"We have a constant project plan item to work on hardening API that has
been introduced as provisional in the previous release".

which says that it's an item to work on, regardless of to what extent the goal
is reached.

Provisional API should be in public packages and has clear javadoc that would:
But that's exactly what's happening. The packages are public today. They
just have some "internal" segment in their name. Perhaps what you're missing
is some clear indication in the package name that separates provisional API
from all the wade of other internal stuff. That's something worth discussing
and specifying. As far as I know, some projects have adopted a naming scheme


which is lengthy but does provide the requested separation. I'm against placing
provisional API into non-internal packages since it would way too easily be
taken for hardened. Although some API Tooling tags could perhaps help here.

Coming up with a generally recommended naming scheme for provisional
API might be worth another bug on the Architecture Council component for

Thanks for bringing up the issue and being persistent. I think that we're
touching on some important issues here, and I'm looking forward to the
followup discussions.

Martin Oberhuber, Senior Member of Technical Staff, Wind River
Target Management Project Lead, DSDP PMC Member

From: eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx [mailto:eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx] On Behalf Of Krzysztof Daniel
Tuesday, October 21, 2008 11:29 AM
E4 developer list
RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat

Hi Martin,

The sources you have mentioned also say:
[2] After the API freeze, there is really no such thing as "provisional API". Either it is complete and committed platform API, or it is internal code.
Moreover it reads:
[2] Technically, a provisional API can change arbitrarily or be removed at any time without notice.
I believe that this document indicates that there is strong "API"-"Internal" division after the release (and maybe this is only my interpretation).

In the [4] I have found interesting table:
Test Suite
Support Promise
Platform API
not quite

The table is bigger of course, but only those two cases are important for us. Note the public package in the provisional API. It is contradictory to the [2] unless provisional API becomes API after every release.

I am happy to see that someone is already using provisional API independent from release cycle, even happier that The TPTP project uses Provisional APIs for all new API introductions: the new API is released as provisional in release X and then hardened into platform APIs in release X+1. (4)

Maybe it would be good to ask TPTP team how this approach works in real environment?

What I'd expect from Eclipse is to adopt slightly modified TPTP strategy - harden provisional API when it has not changed for one development cycle. Provisional API should be in public packages and has clear javadoc that would:
* warn the user that the API *may* change.
* encourage the user to register to particular mailing list/watch some wiki pages

On the other hand we could think about support from API tools, that would throw warnings/errors when the client access provisional API, and about completely new tool that would ask the user to register on mailing list, display messages from developer etc.


Commiter A creates:
package org.eclipse.component;
* This is provisional API. It is believed to be stable, but still may change. For your own good subscribe to the list component-dev-provisional to be notified about changes.
* @provisional
* @since 3.5
public interface IInterface{
public void method1();
public void method2();

Now some client implements that interface. It is warned (by API tools) and prompted to register to the newsgroup. During the development cycle we may ask clients if they got what they expected and if we can do anything better.

Eclipse 3.5 is released. A lot of people uses that interface, and it appears that third method is necessary. So the commiter adds method3(), posts to concrete mailing list and all customers are informed about compatibility breaking change. Also steps necessary to adapt new method are described (and in the future maybe some more advanced refactoring scripts).

Eclipse 3.6 is released with that change, than 3.7 without change, so the @provisional tag should be deleted and... no refactoring at that point :-).

I hope that my vision is easier to understand now :-).
[1] EclipseCon 2008 Device Debugging (DD) Update


Christopher Daniel
Technical Support Engineer
Eclipse Support Center
IBM Software Group _______________________________________________
eclipse-incubator-e4-dev mailing list

eclipse-incubator-e4-dev mailing list

GIF image

GIF image

GIF image

Back to the top