Re: [eclipse-pmc] Publishing 0.9 API's for new components

[Boris Bokowski <Boris_Bokowski@xxxxxxxxxx>]

> The challenge is that we are not confident in the shape of "the
> stuff that consumers should call".  Worse, there is some of that stuff
that
> people will have to call for p2 (or API Tooling) to be integrated into
the
> SDK.

If this is the case, it should not be API, nor should it be in a package
that looks as if it was API.  I sometimes think of an API as a promise, so
if you cannot promise that you will be able to maintain the interface, make
it internal. This does not rule out that you can have contracts between you
and other *known* parties about what they can expect in future releases.
The key is to know the other parties (and their release schedules...) so
that you know what you can change and when.

> Clearly the unambiguously internal should be marked as x-internal := true
> and has "internal" in the package name.   But what do we do about the
stuff
> that people are supposed to call but we cannot guarantee?  Putting it in
an
> internal package blurs the distinction and hinders early adopters.  We
can
> use "provisional" as a human readable distinguisher.

I would recommed making it internal, but separating the API candidates into
their own package (internal.provisional ?) so that it is easier to explain
to early adopters which part of your code you want them to call.

>  That still leaves the
> question of x-internal := true.  Setting it to "false" (or omitting the
> directive) is signals its interest to consumers but is inaccurate wrt
> API-ness.  Setting the directive to "true" solves that problem but forces
> all consumers to either live with the warnings or turn them off.

My gut feeling is that you want x-internal:=true so that clients don't call
internals inadvertently.  We could solve the warnings problem with a
modifier on Require-Bundle/Import-Package, something like: "Require-Bundle:
org.eclipse.equinox.p2;forced-friend:=true" - what do you think?

> There is a further issue of whether or not we have the extra segment
> (internal or provisional) in the package name thereby forcing all to
change
> their code when we finally do graduate.

IMO, forcing all to change is a good thing. This makes it clear that you
really need a contract between you and early adopters, and that graduating
means a coordinated change involving all of these known parties.  If you
are lucky, all they have to do is organize imports; doesn't sound too bad
to me given the tooling that we have.

> Finally, what Darin suggested (using 0.9) is the superficial equivalent
of
> "not graduating" the function.  That is, would we ship incubator content
in
> 3.4?

How is this different from shipping a 1.0 version and then, if you need
breaking changes, shipping a 2.0 version in the next release?

Boris