Difference between revisions of "MoDisco/API Policy"

Revision as of 11:58, 11 March 2011

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

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

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.

Examples API

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 Use

Internal code is everything else. MoDisco reserves the right to change internal code at any time.

The internal packages should contain 'internal' in the package name The internal packages should not appear in "Exported Packages" in manifest file. Note : within MoDisco components, x-friends|x-internal can be used in the manifest to give 'internal' access to any plugin from the same layer that requires it, in such a case it is accurate to write a API.readme.txt file at the top level of the project to justify why one of its internal package is exposed.

Internal extension points should be indicated by 'internal' in the extension point name.

Internal model API (rare) should be indicated by 'internal' in the 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.

Deprecated API declaration

When an API need to be declared deprecated, the contributor has to:

• Add the @Deprecated tag in the Java code.
• Open a bug:
  • having a summary starting with [Deprecated],
  • specifying in which version the API will be removed.
• Copy the bug URL in the Java code of the deprecated API.
• Add in the Javadoc comment using the @deprecated tag:
  • an explanation of what to do when we are using the deprecated API,
  • the version number of the deprecation,
  • the bug URL.