Architecture Group documentation
API guidelines for committers to follow

Definition
API consists of external Java elements such as packages, interfaces, classes, methods, constructors, and fields. Refer to API Java Elements for a discussion of what constitutes an API.

In TPTP, there are three types of API: internal, provisional, and public.

Internal means that no one can use that code outside of the plug-in itself. Internal code has the word "internal" in the package name. Internal code can change at any time.

Provisional means that anyone can use it, but user beware. There are two classes of provisional API: experimental and stable.
  1. Experimental provisional API is API that has a high risk of change in the next release. Code that is experimental has the word "provisional" in its package name.
  2. Stable provisional API is API that probably will not change in the next release. Code that is stable has the @provisional tag in the Javadoc. Stable API is solid but is not public for any number of reasons: the implementation may fluctuate, the function's quality isn't as high as we'd like it to be yet, ports to other platforms may be needed, etc.
Public means that anyone can use it and backward and forward binary compatibility is guaranteed in a maintenance release, and maintained as much as possible in API-breaking level releases. For example, any significant public API that existed in the X.0.0 release will be maintained throughout any maintenance release of X.0, such as X.0.1, X.1, or X.1.1. If TPTP does intend to break an api then TPTP deprecates for a full major release first. All resources (like EMF files) will be migrated transparently when needed. Code whose package name does not include the word "internal" or "provisional", and whose Javadoc does not have the @provisional tag, is public.

Compatibility with previous releases
TPTP X will be compatible with TPTP X-1. The following specifies details of the various aspects of release compatibility.

API Contract Compatibility
TPTP SDK X will be upwards contract-compatible with TPTP SDK X-1. Downward contract compatibility is not supported. There is no guarantee that compliance with TPTP SDK X APIs would ensure compliance with TPTP SDK X-1 APIs. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain contract compatibility.
Binary (plug-in) Compatibility
TPTP SDK X will be upwards binary-compatible with TPTP SDK X-1. Downward plug-in compatibility is not supported. Plug-ins for TPTP SDK X will not be usable in TPTP SDK X-1. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain binary compatibility.
Source Compatibility
TPTP SDK X will be upwards source-compatible with TPTP SDK X-1. This means that source files written to use TPTP SDK X-1 APIs might successfully compile and run against TPTP SDK X APIs, although this is not guaranteed. Downward source compatibility is not supported. If source files use new TPTP SDK APIs, they will not be usable with an earlier version of the TPTP SDK.
Workspace Compatibility
TPTP SDK X will be upwards workspace-compatible with TPTP SDK X-1 unless noted. This means that workspaces and projects created with TPTP SDK X-1 can be successfully opened by TPTP SDK X and upgraded to a X workspace. This includes both hidden metadata, which is localized to a particular workspace, as well as metadata files found within a workspace project (e.g., the .project file), which may propagate between workspaces via file copying or team repositories. Individual plug-ins developed for TPTP SDK X-1 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; X plug-in developers are responsible for ensuring that their plug-ins recognize earlier version metadata and process it appropriately. User interface session state may be discarded when a workspace is upgraded. Downward workspace compatibility is not supported. A workspace created (or opened) by a product based on TPTP X will be unusable with a product based an earlier version of TPTP. Visible metadata files created (or overwritten) by TPTP X will generally be unusable with earlier versions of TPTP.
Non-compliant usage of APIs
All non-API methods and classes, and certainly everything in a package with "internal" in its name, are considered implementation details which may vary between operating environment and are subject to change without notice. Client plug-ins that directly depend on anything other than what is specified in the TPTP SDK API are inherently unsupportable and receive no guarantees about compatibility within a single release much less with an earlier releases. Refer to How to Use the Eclipse API for information about how to write compliant plug-ins.

Questions and Answers
  1. If you have an extension point, and you want to make it internal, is it okay to have the part of the extension point id include "provisional" or "internal"?
    • Yes, extension points follow the same criteria as code, i.e., put "provisional" in the id name or comments in the plugin.xml file.
  2. Should TPTP code use other TPTP provisional code?
    • In a GA stream, we should not be using provisional API because that provisional function is being exposed in the GA quality code. We should also not be using "internal" across plug-ins because we need to guarantee that we're binary compatible across drivers. By using provisional or internal API, you're exposing yourself to the risk that if someone installs two different levels of that plugin, then they could break. If you do use internal TPTP code inside of TPTP then you have to use great care. Make sure that those cross-dependencies don't go outside of a feature group. If you go across a feature group then you're definitely in trouble.
  3. Does stable provisional code put "provisional" in the package name?
    • Stable provisional does not put "provisional" in the package name because you don't want the consumers of the API to be forced to migrate; it enables binary compatibility. If you're not sure that the API won't change, then force the issue: make it obvious that there is no backward compatibility, or that it may change, or that it may go away, by putting "provisional" in the package name.
  4. What are the requirements for declaring API "public"?
    • Public API must have Javadoc or documentation that explains how to use the API correctly. In addition, every method on every public class must have an automated test case that can be run to verify that the API works.
  5. Does the build generate javadoc for provisional as well as internal and public API?

Related articles

Eclipse Quality