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

[Michael Elder <mdelder@xxxxxxxxxx>]

 

   Could we expose these "provisional" APIs through another medium? Perhaps a page on the website that lists the "Proposed" features (using only the "internal" naming convention) and request feedback on those areas for clients that experiment with using those classes in their products (note I didn't use the phase "API" here)?

 

Jim -- would that still be sending the "mixed message"? What's the practice normally used by other Eclipse teams when experimenting? Do we fall into a different situation since we have so much functionality and code that has evolved in a commercial setting which we are now refactoring into tight, open client API?

 

 

-------------------------------------------------------------------------

Kind Regards,

 

Michael D. Elder

Rational Studio / J2EE Tools Development     

IBM RTP Lab

Ext: (919) 543-8356

T/L: 441-8356

mdelder@xxxxxxxxxx

 

 

 

Tuesday, March 08, 2005 4:07 PM
To: wtp-dev@xxxxxxxxxxx
cc:
From: Arthur Ryman <ryman@xxxxxxxxxx>
Subject: Re: [wtp-dev] proposed package naming convention to distinguish 'work in progress' API

Jim, 

The message we are trying to send is that 
some code is never intended to become API, but other code is, although it is not 
ready yet. Code that is never intended to be used outside the component is 
clearly "internal". 

However, we find 
ourselves in a paradoxical situation. Because we are setting very high standards 
for API code, we are going to ship WTP 1.0 with only a subset of the API 
defined. This means that adopters of WTP 1.0 may need to use non-API code. They 
do so at their own risk, since the non-API code will surely change. However, we 
want to give some guidance to adopters. It is far better if they use non-API 
code that is on the API track, rather than arbitrary internal code. 

As you suggest, we can certainly add 
documentation to the internal code that state it is destined to become API. 
However, I think it would be useful if we also established a project-wide naming 
convention to make this situation clear. 

I believe it is a very common situation for a project to have code that 
is on the API track, but not yet ready for prime time. A naming convention would 
make this situation clear to everyone. 

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/

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

03/08/2005 03:39 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

Without specs, test suites, and all the other things that come with 
sustainable APIs, they can't really be considered APIs, not even 
provisional or interim ones. Using packages names with "internal.api" or 
"internal.provisional" sends a mixed message. 

I'm not sure what 
problem would be addressed by embedding something 
additional in the package 
name. 

---jim




Craig Salter/Toronto/IBM@IBMCA 
Sent 
by: wtp-dev-admin@xxxxxxxxxxx
03/08/2005 03:10 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







Or perhaps "internal.api.XXX". 
 Might be more obvious.

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




Jeffrey Liu/Toronto/IBM@IBMCA 
Sent by: wtp-dev-admin@xxxxxxxxxxx 
03/08/2005 03:05 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









Can we use 'internal.provisional' to 
indicate work in progress APIs? On 
one hand, we are saying, use these APIs 
at your own risk (internal 
package). On the other hand, developers that 
follow this mailing list will 
know that APIs inside the 
"internal.provisional" package have a better 
chance of becoming a real API. 

Thanks, 

Jeffrey Liu
IBM Rational Software - Performance 
Analyst
IBM Toronto Lab.
8200 Warden Ave. Markham, Ontario, L6G 
1C7
Internal mail: D3/R8V/8200/MKM (D3-268)
T/L: 969 3531
Tel: (905) 
413 3531
Fax: (905) 413 4920
jeffliu@xxxxxxxxxx


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


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