Thread-topic: [eclipse-pmc] Provisional API guidelines
+1, two more points:
While manifest markup should be mandatory, Javadoc markup
("@provisional") should also be encouraged in addition to that. Think about
generated Javadocs read on a web server, where the manifest is not available
(and yes I do know that whether provisional API should be generated as
Javadocs or not is a separate question).
Provisional API can be distinguished from internal code today, when the
internal code has a **/internal/** path segment. Perhaps this could be
leveraged by tooling if related filters are
[mailto:eclipse-pmc-bounces@xxxxxxxxxxx] On Behalf Of John
Arthorne Sent: Thursday, March 18, 2010 3:40 PM To:
eclipse-pmc@xxxxxxxxxxx Subject: Re: [eclipse-pmc] Provisional API
These points have won me over to the
side of manifest markup, in particular the need for pure binary bundles to
indicate their API-ness regardless of availability of javadoc. However at this
point in the release cycle I'm not sure the framework and tooling teams have the
time to implement new manifest markup and tooling in time for Helios.
In the end this seems like a nice
thing to have, but seems separate from whether we adopt your proposed new
provisional API guidelines. With both old and new guidelines, provisional API is
marked x-internal. A different manifest attribute would make it a little easier
for clients to distinguish their use of internals from use of provisional,
presumably with the benefit that they can ignore warnings about using
provisional API without ignoring warnings about other internals. This doesn't
seem like an urgent enough benefit for us to push on getting this supported
added for Helios.
<jeff@xxxxxxxxxxxxxxxxx> Sent by: eclipse-pmc-bounces@xxxxxxxxxxx
03/15/2010 02:20 PM
Re: [eclipse-pmc] Provisional API
reason I liked the manifest markup is for "consistency" with the
x-internal/x-friends tags which really talk about what is API and who can use it
(e.g., the contract). Having said that, there is an element of history here.
Traditionally the manifest markup was what was driving the tools. With the
advent of API tools etc, this kind of JavaDoc markup is more interesting. Some
- You must be able to ship a binary
bundle and indicate what parts are provisional such that I get errors when I
develop code using those provisional API (assuming I say I don't want to use
provisioning bits) then we have the bulk of the function we need.
- Have to talk about how to indicate
provisional-ness on packages. In the package.html? Where?
- Reconcile the multiple locations for markup related to
package API-ness (some in manifest, some somewhere else, ...)
Summary: I would like there to be some markup.
On 2010-03-15, at 2:03
PM, John Arthorne wrote:
week's PMC call, we discussed formally adopting Jeff's proposed update to our
provisional API guidelines . Overall we were in agreement on the direction,
but the question was raised whether additional markup and tooling were needed to
distinguish provisional API from other internal packages. One approach to doing
this would be additional manifest markup as described in bug 234947
I have been
thinking that another approach would be a javadoc tag such as @provisional in
the code itself. One advantage of this is that it puts markup directly in the
code where clients are more likely to see it even if their tools are configured
to ignore the warnings. It would also allow for finer-than-package granularity
of provisional API, although I'm not convinced we need or want that. Conversely,
manifest markup allows multiple providers of the same package to declare
different intent (one could export a package provisionally, while another might
declare as full API). I'm not sure if that use case makes any sense, I'm just
trying to think through what advantages manifest markup has over markup in the
code itself. I must be missing some reasons here but hopefully Jeff and Tom can
chime in on that.