RE: [eclipse-pmc] Provisional API guidelines

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

I do like the idea of there being some
indication in the javadoc that the API is provisional. Do you think it
is valuable to define a javadoc tag for this, or just have a paragraph
explaining it? In the past we have just added a blurb like this into the
class javadoc:

 * <b>Note:</b>
This class/interface is part of an interim API that is still under development
and expected to
 * change significantly
before reaching stability. It is being made available at this early stage
to solicit feedback
 * from pioneering adopters
on the understanding that any code that uses this API will almost certainly
be broken
 * (repeatedly) as the
API evolves.

John

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

03/18/2010 10:51 AM

Please respond to
eclipse-pmc@xxxxxxxxxxx

To	<eclipse-pmc@xxxxxxxxxxx>
cc
Subject	RE: [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 provided?

Martin

---

From: eclipse-pmc-bounces@xxxxxxxxxxx
[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 guidelines


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.

John

Jeff McAffer <jeff@xxxxxxxxxxxxxxxxx>
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx

03/15/2010 02:20 PM

Please respond to
eclipse-pmc@xxxxxxxxxxx

To	eclipse-pmc@xxxxxxxxxxx
cc
Subject	Re: [eclipse-pmc] Provisional API guidelines

The 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 random thoughts: 

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

Jeff 


On 2010-03-15, at 2:03 PM, John Arthorne wrote: 


At last week's PMC call, we discussed formally adopting Jeff's proposed
update to our provisional API guidelines [1]. 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 [2]. 

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. 

John 


[1] http://wiki.eclipse.org/Provisional_API_Guidelines_Update_Proposal
[2] https://bugs.eclipse.org/bugs/show_bug.cgi?id=234947_______________________________________________
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
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc