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 API Contract
This document is meant for COSMOS committers. 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.