Jump to: navigation, search

Difference between revisions of "WTP API Policy"

m (WTP API Policy)
m (WTP API Policy)
Line 8: Line 8:
  
 
== Declared API ==
 
== Declared API ==
Declared API is public API that WTP has committed to supporting for several releases.
+
Declared API is public API that WTP has committed to supporting for several releases. It should be clean and contain adequate javadoc.
  
 
New API must be reviewed by the project lead. It must be frozen by the release API freeze date and will not change throughout the remainder of the release or the corresponding maintenance stream.
 
New API must be reviewed by the project lead. It must be frozen by the release API freeze date and will not change throughout the remainder of the release or the corresponding maintenance stream.
Line 27: Line 27:
  
 
== Protected Internal Usage ==
 
== Protected Internal Usage ==
Protected internal usage are internal methods that have reported by adopters in API usage scans, and WTP has agreed not to change.
+
Protected internal usage are internal methods that have been reported by adopters in usage scans and WTP has agreed to maintain.
  
** Protected internal usage must be maintained and deprecated as declared API. There are three possibilities for this code to be evolved (terms defined below):
+
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.
 +
 
 +
During regular development milestones, protected internal usage may only be changed if necessary, after reasonable notification (including information on new API or a migration path), and/or discussion with adopters. Protected internal usage may not change after the regular API freeze date of a release and will be treated like declared API for the remainder of the release and the corresponding maintenance releases.
 +
 
 +
There are several possibilities for protected internal usage to evolve:
  
 
:*Declare API - If equivalent API has been created, the code may be deprecated and removed after one full release.
 
:*Declare API - If equivalent API has been created, the code may be deprecated and removed after one full release.
 
:*Declare provisional API - If equivalent provisional API has been created, the code may be deprecated and removed after one full release.
 
:*Declare provisional API - If equivalent provisional 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.
+
:*Unprotected internal usage - If the code is deemed illegitimate (unprotected) internal use, the adopter will be notified and the use will be removed from the protected internal usage scans. In cases where the usage is questionable, WTP may question the adopter on why the internal code is being used. If the use is not acceptable after a reasonable discussion, it may be deemed unprotected.
:*Unprotected usage - If the code is declared as illegitimate internal use, it is regular internal code and may change at any time.
+
:*Adopter agreement - If the code dependencies are minimal or the adopter no longer needs it, ** it is regular internal code and may change at any time.
+
  
-becomes API in 2 releases
+
::The following are some examples of illegitimate internal usage:
-three options: declare as API, provisional, or get agreement with adopter to drop it **
+
::* Use of messages, icons, logging or tracing methods from another plugin.
-no breakage after API freeze
+
::* Use of internal methods where equivalent API exists. (In cases where new API is declared, reasonable time should be given for porting)
-provisional + reasonable notice (new API, migration path, etc.)
+
::* Use of internal utility classes unrelated to the purpose of the plugin.
  
 +
:*Adopter agreement - If the adopter no longer needs it or code dependencies are minimal, the adopter may agree to remove or reduce the protected internal usage scans.
 +
:*Project graduation - If a WTP project has well defined API and minimal internal usage, it may request 'graduation' from the PMC for the protected internal use policy. If there are no serious issues raised, the project will no longer follow this section of the API policy. All internal usage will be treated like regular internal usage described below.
  
 +
Any protected internal use that has not evolved in one of these directions after two releases (WTP '4.0') will default to declared API, and WTP projects will have to follow regular declared API rules when changing this code.
  
==== Grandfathering of Internal Usage Scans ====
+
== Internal Use ==
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.
+
Internal code is everything else - usually indicated by 'internal' in the package or extension point name. WTP reserves the right to change internal code at any time.
  
==== Protected (Legitimate) Internal Usage ====
+
If adopters require the use of internal code and do not want to be continually broken, they should open bugzilla enhancement requests for API. These bugs will be triaged and will help drive new declared or provisional API.
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 protect any references in usage scans that are deemed illegitimate.
+
 
+
What this means is that any obvious illegitimate usage may be removed from usage scans and not 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.
+
 
+
==== Graduation ====
+
Components or projects that believe they have adequate API coverage and minimal protected 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.
+
 
+
== Internal ==
+
Internal code is everything else - usually indicated by 'internal' in the package or extension point name. WTP reserves the right to change internal code at any time.
+
  
Due to the minor risk that we may break an adopter we'll try not to change any internal code that is accessible by adopters (i.e. internal public and protected classes and methods) in a maintenance stream. However, as in any internal code we do reserve the right to make changes at any time.
+
Due to the minor risk that we may break an adopter we will attempt to not to change any internal code that is accessible by adopters (i.e. internal public and protected classes and methods) in maintenance releases. However, as in any internal code we reserve the right to make changes at any time.

Revision as of 16:39, 31 October 2007

WTP API Policy

DRAFT

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 API policy that will allow us to innovate while still encouraging widespread adoption.

Declared API

Declared API is public API that WTP has committed to supporting for several releases. It should be clean and contain adequate javadoc.

New API must be reviewed by the project lead. It must be frozen by the release API freeze date and will not change throughout the remainder of the release or the corresponding maintenance stream.

In following releases, API may sometimes be deprecated due to the normal evolution of WTP. Deprecations must be approved by the project lead and must contain information on a migration path for existing adopters. Deprecated API may not be removed for at least 2 major releases (and preferably longer). Exceptions must be approved by the PMC.

Provisional API

Provisional API is tentative/interim API. It is marked as provisional in the class javadoc comments, and is still under development and likely to change. It is used to provide temporary API and request feedback from the community.

Provisional API must be finalized by the regular API freeze date of a release and will be treated like declared API for the remainder of the release and the corresponding maintenance releases. In the next release, provisional API will typically evolve in one of the following ways:

  • Declared as API (possibly with change).
  • Modified to reflect feedback and remain as provisional API in the next release to get additional feedback.
  • Removed (and usually replaced by new API or different provisional API).
  • Deprecated and removed in the next release.

It is our intention that provisional API should not stagnate. Its purpose is to obtain feedback from the community and evolve in the following release.

Protected Internal Usage

Protected internal usage are internal methods that have been reported by adopters in usage scans and WTP has agreed to maintain.

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.

During regular development milestones, protected internal usage may only be changed if necessary, after reasonable notification (including information on new API or a migration path), and/or discussion with adopters. Protected internal usage may not change after the regular API freeze date of a release and will be treated like declared API for the remainder of the release and the corresponding maintenance releases.

There are several possibilities for protected internal usage to evolve:

  • Declare API - If equivalent API has been created, the code may be deprecated and removed after one full release.
  • Declare provisional API - If equivalent provisional API has been created, the code may be deprecated and removed after one full release.
  • Unprotected internal usage - If the code is deemed illegitimate (unprotected) internal use, the adopter will be notified and the use will be removed from the protected internal usage scans. In cases where the usage is questionable, WTP may question the adopter on why the internal code is being used. If the use is not acceptable after a reasonable discussion, it may be deemed unprotected.
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.
  • Adopter agreement - If the adopter no longer needs it or code dependencies are minimal, the adopter may agree to remove or reduce the protected internal usage scans.
  • Project graduation - If a WTP project has well defined API and minimal internal usage, it may request 'graduation' from the PMC for the protected internal use policy. If there are no serious issues raised, the project will no longer follow this section of the API policy. All internal usage will be treated like regular internal usage described below.

Any protected internal use that has not evolved in one of these directions after two releases (WTP '4.0') will default to declared API, and WTP projects will have to follow regular declared API rules when changing this code.

Internal Use

Internal code is everything else - usually indicated by 'internal' in the package or extension point name. WTP reserves the right to change internal code at any time.

If adopters require the use of internal code and do not want to be continually broken, they should open bugzilla enhancement requests for API. These bugs will be triaged and will help drive new declared or provisional API.

Due to the minor risk that we may break an adopter we will attempt to not to change any internal code that is accessible by adopters (i.e. internal public and protected classes and methods) in maintenance releases. However, as in any internal code we reserve the right to make changes at any time.