This policy defines rules which give some guarantees to adopters about the MoDisco API stability.
We consider MoDisco API as the union of Java API, Eclipse Extension points, and also Models.
Indeed, since the MoDisco project addresses Model-Driven Reverse Engineering, it proposes various metamodels definitions and conforming models to support the end-user use cases.
Declared API is public API that MoDisco has committed to supporting for several releases. It should be clean and contain adequate javadoc. Declared API may evolve in the first few milestones, but 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 MoDisco. Deprecations must contain information on a migration path for existing adopters. Deprecated API may not be removed for at least 1 major release (and preferably longer), and after notifying the community.
Provisional API is a work in progress towards fully Declared API and can be used when committers want to gather community feedback before declaring API, or when there are known problems with a new API that cannot be addressed by API freeze date. Provisional API status is meant to be a temporary state and API should not remain provisional for an undue length of time.
Provisional Java API should be marked at the class or member level with the following javadoc comment:
/** Provisional API: This class/interface is part of an interim API * that is still under development and expected to * change before reaching stability. */
Provisional Model API should be marked at the ecore level with a metamodel identifier mentioning “incubation” (e.g. “http://www.eclipse.org/MoDisco/Java/0.2.incubation/java” as nsURI identifier of an ecore definition). Java model API, because it is generated from ecore model, shouldn't have to be marked as provisional accordingly to the ecore definition.
Provisional Extension Point API should be marked as “incubation” in extension point naming.
The project delivers some examples plugins for various MoDisco features. It includes some models conforming to MoDisco infrastructure and technologies layers, and some Java API. Those components might be used as a starting point for the end-user reverse engineering process. But Examples API is not as stable as declared API and is expected to change.
Any resource included in a plugin whose name indicates 'examples' should be considered of Example API kind.
In addition the project delivers some tests plugins for various MoDisco features. It also includes some models and Java classes, which are not as stable as declared API.
Any resource included in a plugin whose name indicates 'test' should be also considered of Example API kind.
Internal code is everything else. MoDisco reserves the right to change internal code at any time.
Java internal API should be indicated by 'internal' in the package name, or tagged as 'x-internal' in a manifest file. (within MoDisco components, x-friends can be used in the manifest to give 'internal' access to any plugin that requires it).
Extension points should be indicated by 'internal' in extension point name.
Model internal API (rare) should be indicated by ‘internal’ in identifier.
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.