[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [eclipse-dev] Best practices for provisional APIs
|
Provisional APIs are like real APIs in everything except the possibility
that they might change. Like real APIs, provisional APIs should be well
documented with all the Javadocs in place, well designed with names and
signatures that look real. If provisional APIs are treated seriously and
not changed gratuitously, they can serve a similar purpose of house bills
put through the process of becoming laws.
If I read the disclaimer and accept that I can be broken, I can use the new
function and provide necessary feedback to the developers. If I make myself
known to the developers, they will appreciate early adopters and give them
heads up when they need to make a breaking change. Sometimes this change
may be initiated by the early adopters themselves as a result of feedback.
I think that APIs that look real except for the disclaimer in Javadoc serve
a useful purpose as long as they don't stay in that stage forever (like a
student who never actually graduates :-).
Regards,
Dejan Glozic, Ph.D.
Manager, Eclipse Development 1A
D1/R0Q/8200/MKM
IBM Canada Ltd.
Tel. 905 413-2745 T/L 969-2745
Fax. 905 413-4850
Jeff
McAffer/Ottawa/IB
M@IBMCA To
Sent by: eclipse-dev@xxxxxxxxxxx
eclipse-dev-bounc cc
es@xxxxxxxxxxx
Subject
Re: [eclipse-dev] Best practices
02/17/2006 10:11 for provisional APIs
AM
Please respond to
"General
development
mailing list of
the Eclipse
project."
There is a third type. Code that is not intended to be used by others at
all. That is the intended/historical meaning of "internal". As such,
marking things internal with no indication that they are candidates for
being API may scare them off too much. Often what we need for these
provisional API to become real is user involvement. The data bindings are
a good example. The UI team did not feel confident in the current shape
but yet would like people to look at the API and, to the extent that they
are willing to be broken going forward, use them and give feedback. To
facilitate this, we need to communicate to them, which classes/methods are
candidates. This also plays on Pascal's question about how to encourage
people to give that feedback. To facilitate that, it might be useful to
mention giving feedback as a sign to users that we are interested in their
input. Giving a location for that feedback would be useful.
As for package naming, I have never been a fan of *.internal.provisional.*.
One or the other should be enough. I would however encourage people to put
their provisional API classes together by domain in packages. That is,
package it as if it were API so that people can understand the shape.
As for Javadoc, we have long had a standard template for marking things
experimental/provisional. We should continue using that form (potentially
with a feedback statement) unless there are issues with it.
Jeff
Mike Wilson/Ottawa/IBM@IBMCA
Sent by: To
eclipse-dev-bounces@eclipse. "General development mailing list
org of the Eclipse project."
<eclipse-dev@xxxxxxxxxxx>
cc
02/17/2006 09:01 AM
Subject
Re: [eclipse-dev] Best practices
Please respond to for provisional APIs
"General development
mailing list of the Eclipse
project."
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
To
eclipse-dev@xxxxxxxxxxx
02/17/06 08:44 cc
Subject
Please respond to [eclipse-dev] Best
"General development mailing list of practices for provisional
the Eclipse project." 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
_______________________________________________
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
