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

I think this is a reasonable balance between transparency of intent and
honest admission of the current state.

-----Original Message-----
From: wtp-dev-admin@xxxxxxxxxxx [mailto:wtp-dev-admin@xxxxxxxxxxx] On
Behalf Of Jim des Rivieres
Sent: Thursday, March 10, 2005 11:11 AM
To: wtp-dev@xxxxxxxxxxx
Subject: Re: [wtp-dev] proposed package naming convention to distinguish
'work in progress' API

Arthur,    Your last note clarified a lot of things. I've now come
around 
to seeing it more your way. Here's my current understanding:

To summarize, the situation we will have is this: WTP 1.0 will have some

official, supported APIs. However, some important functionality that 
exists internally will not be accessible through those APIs. The
intention 
is to make this functionality available to all via official, supported
API 
in a follow-on WTP release (i.e., 1.1). Until that time, there is no 
official and supported way to do this.

Clients of WTP 1.0 have to make the tough choice between:
(1) Living within the means provided by WTP 1.0 APIs. These APIs are 
stable. Clients that use them according to spec will work with WTP 1.0
and 
compatible follow-on WTP releases.
(2) Using the WTP 1.0 APIs and also using WTP internals to access 
functionality that is not yet supported at the API. Clients that do this

are likely to work only with WTP 1.0. These clients will not work with 
compatible follow-on WTP releases because they depend on WTP internals 
which are almost certain to be gutted and replaced when this
functionality 
is exposed as official, supported API. A porting effort will be required

to wean the code off the internals and onto the extended official, 
supported WTP APIs.

Besides making the WTP 1.0 APIs as capable and possible in the time 
remaining before WTP 1.0 ships, it feels like the greatest service we
can 
provide our clients is to make it crystal clear where things are, so
that 
they are under no illusions about the consequences of the choice they
have 
to make.

I still believe firmly that we'll want everything that's not official, 
supported API to be in a package with 'internal' in the name, as we do 
elsewhere in Eclipse.  But I can see the additional value to some
clients 
by to provide them with additional guidance via package names about
where 
to find the extra functionality that is not yet surfaced through the API

but will likely be, in some form, in follow-on releases. And it gives us
a 
chance to steer these clients clear of the code that there is no intent
to 
ever make API.

I couldn't think of anything better than "internal.provisional" in the 
package name (I'm not wild about "internal.api" because it really does 
sounds like it's sending a mixed message.)

---jim




Arthur Ryman/Toronto/IBM@IBMCA 
Sent by: wtp-dev-admin@xxxxxxxxxxx
03/09/2005 09:22 AM
Please respond to
wtp-dev


To
wtp-dev@xxxxxxxxxxx
cc

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

progress' API







Jim, 

I think we are homing in on the real issue, which is the extend and 
usefulness of the initial API. 

I believe that in many areas WTP will have useful API in 1.0, e.g.
Server 
tools. 

I also believe that WTP will be missing APIs for function that upstream 
products currently use. These are non-WTP products, e.g. RAD and 
potentially WebLogic Workshop. Of course, we would like to minimize
that, 
but we don't have the resource to completely define all APIs that
upstream 
products need. We therefore have 2 alternatives: 

1) Status quo - use "internal" in the package name and add comments in
the 
Javadoc to indicate that the code is a candidate API package. 
2) Adopt a project wide package naming convention to indicate that the 
code is a candidate API package. Suggestions for the name include 
"provisional", "candidate.api", "internal.api" 

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 07:09 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








Arthur,

> 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.

I'm not seeing the value of having a highly visible project-wide way of 
marking not-ready-for-primetime-stuff-that-may-become-API-some-day. This

should be just an internal matter for the WTP teams. Why purpose does it

serve to tell the rest of the world about this? After all, we are
telling 
them quite directly not to use the internal stuff. So why tempt them
(and 
us) by codifying a convention that would make it easier for them to
locate 

some of the more interesting things that they should not be using :-)

I think it may also be helpful to separate WTP components from other 
non-WTP components, and look at how we realistically expect them to
behave 

wrt 1.0 WTP APIs.

For non-WTP components:
- these clients are expected to use only the official WTP APIs according

to spec
- WTP will support these APIs and evolve them in compatble ways through 
future releases
- all WTP internal packages are off definitely limits for these clients
- clients should enter feature requests for additonal APIs they would
like 

to see in future WTP releases
- clients should not go jump the gun and exploit implementation details
of 

WTP 1.0

For WTP components:
- these clients are expected to use the official WTP APIs according to 
spec
- in limited and mutually agreed on circumstances, one WTP component may

use the internals of another WTP component in order to access 
functionality that is yet to be exposed through APIs
- this not-though-API-coupling can be tolerated to the extent that all
WTP 

components ship on the same schedule and are installed and used as a
unit

> 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. 
When you say this, I read "adopters" as the other WTP components.
Reading 
"adopters" as non-WTP components suggests that we don't think the
initial 
APIs will be useful as-is for clients outside WTP. My expectation is
that 
non-WTP clients would find the initial WTP APIs useful for their
intended 
purpose, just not as fully-functioned as they might have liked
(hopefully 
that will be improved on in future releases). I say this with a straight

face: it should always be possible to write reasonable clients to-spec 
using the initial release of an API. If the only clients that could use 
the API are ones that will also need to subvert the API by using
internals 

as well, it is unclear that any purpose is being served by revealing an 
API at this early a stage.

---jim





Arthur Ryman/Toronto/IBM@IBMCA 
Sent by: wtp-dev-admin@xxxxxxxxxxx
03/08/2005 04: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







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


_______________________________________________
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



Back to the top