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