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

[Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>]

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: eclipse-dev-bounces@xxxxxxxxxxx

02/17/2006 09:01 AM

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

To	"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
cc
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