Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "WTP API Policy"
m (→Protected Internal Usage) |
m (→WTP API Policy) |
||
| Line 28: | Line 28: | ||
== Protected Internal Usage == | == Protected Internal Usage == | ||
| − | Protected internal usage are internal methods that have been reported in adopter usage scans and WTP has agreed to maintain. | + | Protected internal usage are internal methods that have been reported in adopter usage scans and WTP has agreed to maintain. This may include use of provisional API, which is covered by this category. |
As of Nov 30th, 2007, WTP will no longer accept new internal usage scans. We will continue to respect the latest usage scan from all adopters received before Nov 30th. | As of Nov 30th, 2007, WTP will no longer accept new 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 | + | During regular development milestones committers must send a note to the mailing list and to the email address listed in any affected adopter scan 2 (two) weeks before making any breaking change to protected internal usage. The note should include information on what is changing, potential migration paths, if there is a deprecation period, etc. If there is no response within the two weeks or all responses are positive, the committer is free to make the change. |
| − | + | If any adopters object to the change, the committer must work with them to find an acceptable solution. Some possibilities are more information about the change, providing a deprecation period, changing the timing, or additional information to help with porting. If the adopters agree after this discussion, the committer can go ahead with the change. | |
| − | + | If the committer and adopters cannot find a reasonable compromise, the issue will be brought to the PMC for arbitration. The PMC may decide on any solution it feels balances between supporting the adopter community as a platform and allowing innovation and change in WTP. | |
| − | :*Declare | + | |
| − | :*Illegitimate internal usage - If the code is deemed illegitimate internal use, the adopter will be notified and the use will be removed (unprotected) from the usage scans. In cases where the usage is questionable, | + | 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 opportunities for code to evolve out of protected internal usage: | ||
| + | |||
| + | :*Declare as API or declare an equivalent API. | ||
| + | :*Provide provisional API. | ||
| + | :*Illegitimate internal usage - If the code is deemed illegitimate internal use, the adopter will be notified and the use will be removed (unprotected) from the usage scans. In cases where the usage is questionable, a committer may question the adopter on why the internal code is being used. If the use is not acceptable after a reasonable discussion, it may become unprotected. | ||
::The following are some examples of illegitimate internal usage: | ::The following are some examples of illegitimate internal usage: | ||
| Line 46: | Line 52: | ||
:*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. | :*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 | + | :*Project graduation - If a WTP project has well defined API and minimal internal usage, it may request 'graduation' from the PMC from the protected internal use policy. |
| + | |||
| + | Any code covered in the illegitimate internal usage, removed by adopter agreement, or project graduation categories will be treated like regular internal use 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. At that time this section of the policy will be removed. | + | 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 (e.g. deprecation) when changing this code. At that time this section of the API policy will be removed. |
== Internal Use == | == 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. | + | Internal code is everything else - usually indicated by 'internal' in the package or extension point name, or tagged as 'x-internal' in a manifest file. 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 the creation of new declared or provisional API. | 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 the creation of new declared or provisional API. | ||
Due to the 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. | Due to the 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 11:49, 6 November 2007
Contents
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 releases.
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 in adopter usage scans and WTP has agreed to maintain. This may include use of provisional API, which is covered by this category.
As of Nov 30th, 2007, WTP will no longer accept new internal usage scans. We will continue to respect the latest usage scan from all adopters received before Nov 30th.
During regular development milestones committers must send a note to the mailing list and to the email address listed in any affected adopter scan 2 (two) weeks before making any breaking change to protected internal usage. The note should include information on what is changing, potential migration paths, if there is a deprecation period, etc. If there is no response within the two weeks or all responses are positive, the committer is free to make the change.
If any adopters object to the change, the committer must work with them to find an acceptable solution. Some possibilities are more information about the change, providing a deprecation period, changing the timing, or additional information to help with porting. If the adopters agree after this discussion, the committer can go ahead with the change.
If the committer and adopters cannot find a reasonable compromise, the issue will be brought to the PMC for arbitration. The PMC may decide on any solution it feels balances between supporting the adopter community as a platform and allowing innovation and change in WTP.
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 opportunities for code to evolve out of protected internal usage:
- Declare as API or declare an equivalent API.
- Provide provisional API.
- Illegitimate internal usage - If the code is deemed illegitimate internal use, the adopter will be notified and the use will be removed (unprotected) from the usage scans. In cases where the usage is questionable, a committer may question the adopter on why the internal code is being used. If the use is not acceptable after a reasonable discussion, it may become 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.
- The following are some examples of illegitimate internal usage:
- 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 from the protected internal use policy.
Any code covered in the illegitimate internal usage, removed by adopter agreement, or project graduation categories will be treated like regular internal use 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 (e.g. deprecation) when changing this code. At that time this section of the API policy will be removed.
Internal Use
Internal code is everything else - usually indicated by 'internal' in the package or extension point name, or tagged as 'x-internal' in a manifest file. 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 the creation of new declared or provisional API.
Due to the 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.