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

[Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>]

p2 has the same problem.  we have
large swaths of stuff that we intend for consumers to call and larger swaths
of stuff that they are not supposed to call.  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.  

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.  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.

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.
 BTW, with the state of our current and coming API tooling the value
of using the "internal" segment is IMHO minimal.  It might
be convenient for the bundle writters but with proper filtering, errors/warnings
and build time validation it is unnecessary.

On a different note we have historically
had the need to ship whole bundles that are in effect internal implementation
details.  Tomcat and Xerces spring to mind as examples.  If for
example we had a way to describe non-API *bundles* then we could mark all
of p2 and API tools as not API.

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?

Jeff

Steve Northover/Ottawa/IBM@IBMCA
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx

11/28/2007 04:47 PM

Please respond to
eclipse-pmc@xxxxxxxxxxx

To	eclipse-pmc@xxxxxxxxxxx
cc
Subject	Re: [eclipse-pmc] Publishing 0.9 API's for new components

Here is my initial position: Either something is API or it is not.  If
it is API, then it is not subject to change.  If you are not sure,
don't make it API.

Darin Wright/Ottawa/IBM@IBMCA
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx

11/28/2007 12:56 PM

Please respond to
eclipse-pmc@xxxxxxxxxxx

To	eclipse-pmc@xxxxxxxxxxx
cc
Subject	[eclipse-pmc] Publishing 0.9 API's for new components

PMC,

API tooling work is progressing in the PDE incubator (
http://wiki.eclipse.org/PDE_UI_Incubator_ApiTools). We envision some form
of API tooling to ship with the 3.4 Eclipse release. API tooling itself
will have an API. As with any first release of a component we are hesitant
to commit to a public/stable API that will be supported for all versions
of API tooling to come. I believe there are other components that will
have similar issues in the 3.4 release (p2, for example). Is there some
style/guideline we can follow to publish these "0.9 APIs" that
are subject 
to change?

Thanks,

Darin Wright

_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc