Skip to main content
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
"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
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
at least one customer has been identified and has reviewed the API,
all Javadoc is complete,
at least one JUnit test exists for each method in the API,
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
5. After M4, any change to an API must
be approved by the Planning Group. The input to the Planning Group is:
the component lead champions the change and has assessed the schedule impact,
the Architecture Group has reviewed the change and supports it.
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
Back to the top