Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[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/

Back to the top