Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipse-dev] Best practices for provisional APIs


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


Back to the top