RE: [eclipse-dev] Best practices for provisional APIs

[Randy Hudson <hudsonr@xxxxxxxxxx>]

There is one major difference. Provisional
says "please try out this API and help us define the use cases".
Internal says "we have no idea why you would need to use these classes".
 The similarity is that if you use either, you can be broken in the
next release.

I would prefer just ".provisional"
or ".experimental" prefix in the package name. Clients are more
likely to look at the API, which is the whole point to releasing it in
its "unpolished" state.  Oh .... and it's easier to type.

-Randy

"Ed Burnette" <Ed.Burnette@xxxxxxx>
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

02/17/2006 09:55 AM

Please respond to
"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>

To	"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
cc
Subject	RE: [eclipse-dev] Best practices for provisional APIs

I agree with Mike. "provisional
api" or "internal provisional", whatever you call it, is
just a guess anyway because you reserve the right to change it.

---

From: eclipse-dev-bounces@xxxxxxxxxxx
[mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Mike Wilson
Sent: Friday, February 17, 2006 9:01 AM
To: General development mailing list of the Eclipse project.
Subject: Re: [eclipse-dev] Best practices for provisional APIs


I find the notion of provisional api to be basically just an oximoron.
We should have only two categories: API, and things that are internal because
they haven't yet stabilized/been validated enough to be API.

McQ.

Pascal Rapicault/Ottawa/IBM@IBMCA
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

02/17/06 08:44

Please respond to
"General development mailing list of the Eclipse project."

To	eclipse-dev@xxxxxxxxxxx
cc
Subject	[eclipse-dev] Best practices for provisional APIs

Hi, 

Should we adopt a consistent way to indicate provisional APIs across the
SDK? 
More specifically I'm wondering what are the rules for
- the package name. should the API be in the package where it would belong
if it was real API, or should it be in an internal package?
- the javadoc markup. should the javadoc say: experimental, provisional,
something else? 

Aside from those questions, I propose to add to the javadoc an explicit
request for feedback from the users and explaining where this feedback
should be given (a mailing-list, a bug report, ...)

PaScaL_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev
_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev