Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
COSMOS API Contract
COSMOS Wiki > COSMOS Documents
This document is meant for COSMOS committers and consumers. It provides an overview of how to properly indicate the state of an API in COSMOS. The Eclipse guideline defines three types of APIs:
- Internal
- Provisional
- Public
Internal APIs are only used by the project. Consumers/adopters are strongly discouraged from using any internal APIs.
Provisional is a transitional state between internal and public. A provisional API is an early indication of making an API public. COSMOS reserves the right to change/remove provisional APIs during a release development but changes should be well justified based on community feedback. All provisional APIs MUST be thoroughly commented by committers using standard Java doc notation.
Public APIs are stable and commonly used components by consumers/adopters. A public API remains backward and forward compatible between maintenance release. If a public API needs to be removed, then it must be deprecated for an entire major release before it is removed. Public APIs are major commitments that need to be evaluated carefully. The lifespan of a public API is typically 2 years (depending on release schedule). All public APIs MUST be thoroughly commented by committers using standard Java doc notation.
Picking the Right API State
Committers should typically be conservative in what is exposed as provisional or public. The only API types that should be exposed to consumers are hooks available to further extend the project's capabilities. New APIs that are expected to commonly be used by consumers must first be introduced as provisional. All APIs must first be provisional before transitioning to public. The APIs need to be called out in enhancement design documents and discussed during the architecture/subproject meetings. Where unsure, make an API internal.
Indicating API State
Internal APIs are indicated by including the 'internal' keyword as part of the package name containing the internal classes. Similarly the keyword 'provisional' is used to indicate provisional APIs. The internal or provisional keywords should appear as the fifth token of the package name. The first three tokens are always 'org.eclipse.cosmos', the fourth token is an indication of the subproject, and the fifth token is reserved to indicate the state of the API. For example,
org.eclipse.cosmos.rm.provisional.repository - Indicates a provisional API under the resource modeling subproject org.eclipse.cosmos.rm.internal.repository - Indicates an internal API under the resource modeling subproject
Public APIs are indicated by eliminating the internal/provisional keyword from the package name. For example:
org.eclipse.cosmos.rm.repository - Indicates a public API under the resource modeling subproject