Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] proposed package naming convention to distinguish 'work in progress' API


+1 to David's comments and Craig's original suggestion - if they can co-exist.

Speaking for a component that I believe will have much less public API in WTP 1.0 than I would like, I think there is value in a package name that identifies services which are internal but likely to morph - possibly in a big way - into public and permanent API down the road. Replacing "internal" by "provisional" might be misconstrued by clients. Instead, how about a convention of "internal.api"? The "internal" would keep it clear that clients who need stability should steer well clear (as Jim says), while the "api" would provide, at a glance, a hint to clients that these particular internal classes/interfaces represent an intention to design replacement public API in a future release.

My main concern driving the above is I am not comfortable that we will have sufficient customer review of the proposed API we will try cooking up over the next roughly six weeks. I neither want to declare public API without sufficient review, nor completely discourage customers from identifying, using and assessing internal classes/interfaces that we wish to promote to public API. In summary, "internal.api" really means "candidate", and would invite customers with a need (or just a healthy sense of adventure) to use it, influence its evolution to public status in a later release, and yet remain acutely aware that it's internal and likely to change.

That's my two cents' worth, anyways.

Cheers - CB.

Chris Brealey
Rational Studio Java Web Services, IBM Canada Ltd.
D3-275, D3/ENX/8200/MKM, 8200 Warden Avenue, Markham, Ontario, Canada, L6G 1C7
cbrealey@xxxxxxxxxx, 905.413.6038, tieline:969.6038, fax:905.413.4920



Jim des Rivieres/Ottawa/IBM@IBMCA
Sent by: wtp-dev-admin@xxxxxxxxxxx

03/08/2005 02:08 PM

Please respond to
wtp-dev

To
wtp-dev@xxxxxxxxxxx
cc
Subject
Re: [wtp-dev] proposed package naming convention to distinguish 'work in progress' API





+1 David's comments.  If it wasn't designed as a platform-quality API,
chances are that it will morph somewhat when the API is actually designed.

We use 'internal' in the package name to indicate that the package is not
API and that reasonable clients should stay well clear of it. We should
stick to this simple rule.

To help the dev teams keep track of what is truly internal from what could
be candidate for an API, I suggest putting that information into the
package and class/interface Javadoc.

----jim




David M Williams <david_williams@xxxxxxxxxx>
Sent by: wtp-dev-admin@xxxxxxxxxxx
03/08/2005 01:23 PM
Please respond to
wtp-dev


To
wtp-dev@xxxxxxxxxxx
cc

Subject
Re: [wtp-dev] proposed package naming convention to distinguish 'work in
progress' API







I've had lots of discussions with development teams, and almost all of
them like the idea of kind of "degree of internal" naming. I think,
however, its main value is to the development teams and those working
*real* close to the development teams.

But ... are we talking about released code? Or just temporary,
within-milestone names? If the latter, then nevermind this post. If the
former, I'd be hesitant to have a project standard, for the simple reason
that as a project (and PMC) our promise to clients is only for the APIs
(not "almost APIs" or "API in the future").

I say this partially from experience with early releases of Eclipse, and
some statements from some of those developers of "oh, yes, we intended
that internal package to be API in the future", but by the next release,
the way of providing the function as a supported API was completely
changed (rightly so) , was not a mere rename (rightly so) and caused
upstream clients some unexpected re-work (rightly so). So, in other words,
no matter how good our intent of "we want to make this API in the future"
there's really no good way to predict what it would be like in a future
release, or how much re-work from clients it would entail, once it was
truly designed and made platform quality ... so, we have to be very
careful to give the right message to clients that a "provisional" API is
in no way a partial API or promise for future API.

Having made all these cautionary remarks about correctly setting client
expectations, I'll emphasize I think it's great that teams using something
in addition to "internal" to make their package names more meaningful to
themselves and their clients.

David





Arthur Ryman <ryman@xxxxxxxxxx>
Sent by: wtp-dev-admin@xxxxxxxxxxx
03/08/2005 12:16 PM

Please respond to
wtp-dev


To
wtp-dev@xxxxxxxxxxx, Jim des Rivieres <Jim_des_Rivieres@xxxxxxxxxx>
cc
wtp-dev@xxxxxxxxxxx, wtp-dev-admin@xxxxxxxxxxx
Subject
Re: [wtp-dev] proposed package naming convention to distinguish 'work in
progress' API









Craig,

+1

I think it is very useful to drawn the distinction between code that is
truly internal and code that is on course to become API. Using
"provisional" instead of "internal" works for me.

Another approach might be to use something like "candidateapi" for
candidate APIs, and then change that to "api" when the API is ready.

Jeem - any thoughts?

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@xxxxxxx
intranet: http://labweb.torolab.ibm.com/DRY6/

Craig Salter/Toronto/IBM@IBMCA
Sent by: wtp-dev-admin@xxxxxxxxxxx
03/08/2005 01:37 AM

Please respond to
wtp-dev



To
wtp-dev@xxxxxxxxxxx
cc

Subject
[wtp-dev] proposed package naming convention to distinguish 'work in
progress' API











Hi,

Currently we use 'internal' package names to indicate that code is not
supported API.   I know many of us have code that is 'work in progress'
API and though its too soon to expose this as 'fully supported API' its
seems useful to be able to distinguish these preliminary API's from the
rest of our our 'internal' code.  I'd like to propose that we use
'provisional' in our package names to indicate this sort of work in
progress API.  I think this will help our customers get a better feel for
what parts of our code we eventually intend to promote as API and what
parts we consider to be truly internal.

Any opinions?

thanks

Craig


Craig Salter
Rational Studio XML Web Services
Internal Mail: D3/RY6/8200 /MKM
Phone: (905) 413-3918  TL: 969-3918 FAX: (905) 413-4920
Internet: csalter@xxxxxxxxxx     Notes: Craig Salter/Toronto/IBM@IBMCA


_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/wtp-dev


Back to the top