WTP API Policy
WTP API Policy
In previous releases WTP did not have enough API to meet our adopter's needs and was causing repeated breakage to adopters as we changed our internal code. This led to the adoption of an internal usage scan policy - if an adopter was willing to supply usage data for WTP, we agreed not to change any of the internal code used by the adopter.
This policy was required at the time to stabilize WTP and encourage widespread adoption. However, continuing this policy indefinitely hampers innovation in WTP and makes it difficult to create API. This document provides a new policy that will allow us to innovate while still encouraging widespread adoption. The new policy consists of four sections:
- A grandfather date for accepting new usage scans
- A legitimate usage policy
- Allowance for projects to 'graduate'
- A new deprecation and removal policy
Grandfathering of Internal Usage Scans
As of Nov 30th, 2007, WTP will no longer accept internal usage scans. We will continue to respect the latest usage scan from all adopters received before Nov 30th.
Legitimate Internal Usage
By their nature, internal usage scans include both legitimate usage (code required because equivalent API does not exist) and illegitimate usage (internal code used without good reason). WTP will not respect any illegitimate references in usage scans.
What this means is that any obvious illegitimate usage may be removed from usage scans or flagged as errors in the WTP build. In cases where the usage is questionable, WTP project leads are free to question the adopter for the reason the code is being used. If the reason is not acceptable after a reasonable discussion, the reference may once again be removed from the usage scan data.
The following are some examples of illegitimate internal usage:
- Use of messages, icons, logging or tracing methods from another plugin.
- Use of internal methods where equivalent API exists. (In cases where new API is declared, reasonable time should be given for porting)
- Use of internal utility classes unrelated to the purpose of the plugin.
Components or projects that believe they have adequate API coverage and minimal legitimate internal usage may request 'graduation' from the internal usage scan policy. The method for doing this is not yet defined (PMC review or discussion on wtp-dev?), but if there are no serious issues raised, this project will no longer have to respect internal usage scans. As with other Eclipse projects, internal code may change at any time and adopters would open enhancement requests for any new API or remaining internal usage.
Deprecation and Removal Policy
How we deprecate and eventually remove code is by definition tied to our API policy. WTP's guidelines are provided below:
API should not be deprecated unless absolutely necessary and reviewed by project lead. Deprecated API may not be removed for at least 2 major releases. Exceptions must be approved by the PMC.
Provisional API is interim API that is marked as such, and is still under development and likely to change. Provisional API may be changed or removed at any time, but the usual target is that it has either been declared as API or removed entirely within two releases.
Provisional API that has been declared in a release must be treated like API (and not be broken) in the maintenance stream. In the following release it may be deprecated or changed, but
Legitimate internal usage reported in adopter usage scans must be maintained and deprecated as true API. There are three possibilities for this code to be evolved:
- Declared API - If equivalent API has been created, the code may be deprecated and removed after one full release.
- Project graduation - If the project has graduated from the usage scan policy, the code may be deprecated and removed after one full release.
- Illegitimate usage - If the code is declared as illegitimate internal usage, it may change at any time.
All internal code that is accessible by adopters (i.e. internal public and protected classes and methods) should not be modified or removed in a maintenance stream. While the likelihood may be low, it is not worth the risk of breaking our adopters if we can find other ways to make fixes. Exceptions must be approved by the project lead.