Re: [wtp-dev] API Plan

[Timothy Deboer <deboer@xxxxxxxxxx>]

Hi Arthur,

I've been working steadily on cleaning
up API and have received some great help and advice from Jim. However,
between the server tools framework, Tomcat tools, the TCP/IP monitor, and
the Web browser, I am stretched very thin. This isn't an alarm yet, but
we should discuss and create a plan for getting this done within the given
schedule. If anyone from the community is interested in getting involved,
I would appreciate help in any of these areas.

Thanks,
Tim deBoer
WebSphere Tools - IBM Canada Ltd.
(905) 413-3503  (tieline 969)
deboer@xxxxxxxxxx

Arthur Ryman/Toronto/IBM@IBMCA
Sent by: wtp-dev-admin@xxxxxxxxxxx

02/09/2005 06:04 PM

Please respond to
wtp-dev

To	wtp-dev@xxxxxxxxxxx
cc	Jim des Rivieres/Ottawa/IBM@IBMCA, John Wiegand <John_Wiegand@xxxxxxxxxx>
Subject	[wtp-dev] API Plan

In an earlier note I recommended that we make M4 our API Freeze milestone.
I'd like to clarify what this means and suggest how we should manage the
API definition process. 

I got the following definition from Jeem: 

"We say that come API freeze, a component's API should be in shippable
form and supportable in following releases. It many still need to be some
polishing of the implementation underneath, but it should be just bug fixing
and polishing. All specs and test suites should be in place.

In Eclipse 3.0, we did the freezing in a couple of stages. We had an early
cutoff for breaking API changes to pre-3.0 APIs. This kind of breaking
API changes are always carefully reviewed and approved by PMC before proceeding.
Most of the API changes are in fact non-breaking additions to existing
APIs, or breaking changes to the new APIs that are still "settling".
We expect developers to get all the API work done and in place before the
API freeze. In practice, we get most of the way there, but there are still
some API adjustments that are needed and we let them go in if there's a
good reason to and they don't create problems. This is the slush stage
of the API freeze process. 

As release draws near, a hard API freeze happens. We impose tight controls
on all further API change by instituting a policy that proposed API changes
of any sort (including trivial non-breaking ones) must be described by
a detailed bug report and brought forward to the PMC. The PMC reviews these
changes and weighs the potentially destabilizing effects of changing API
at a late stage of the release cycle versus on the cost of leaving the
API problem unaddressed.  FYI, in 3.0 we approved 50 API changes after
the API freeze; only one was proposed but later withdrawn. All of them
were minor." 

Here are the guidelines I suggest we follow: 

1. The most important reason to define an API is to provide stable interfaces
to a "real" customer. Therefore, Rule #1 is that any WTP API
must have at least one customer. The highest weight will be given to external
customers. In priority order that means 1) Vendors that are planning to
ship products based on WTP,  2) Eclipse projects that plan to use
WTP, 3) other development projects that plan to use WTP, and 4) other WTP
components that use WTP components. 

2. If the only customer for an API is another WTP component then we have
some flexibility. If there is only one other WTP component that needs the
 API, then we should look at merging the two components and defering
the API. Remember that it is OK for plug-ins within a component to use
internal packages. 

3. We need to do a great job on the key APIs and defer definition for others
to future releases when the project has more users and contributors. An
API is a big committment. Any WTP 1.0 API MUST be preserved in future releases,
so it's best for the project if we are very selective about what APIs go
into WTP 1.0. 

4. The M4 exit criteria for each API is: 
        1) at least one customer has been identified
and has reviewed the API, 
        2) all Javadoc is complete, 
        3) at least one JUnit test exists for each
method in the API, 
        4) a short overview document is complete. 
Note that it is enough for the JUnit to exist. It may fail if the API is
not yet implemented. If these exit criteria are not met, then we either
delay the milestone exit, or we pull the API. 

5. After M4, any change to an API must be approved by the Planning Group.
The input to the Planning Group is: 
        1) the component lead champions the change
and has assessed the schedule impact, 
        2) the Architecture Group has reviewed the
change and supports it. 

Comments? 

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/