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.
The user must not implement or extend the API generated by EMF.
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 Internal API kind.
The examples APIs are not stable. They can change without any notice (including in a service release).
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 Internal API kind.
Internal code is everything else. MoDisco reserves the right to change internal code at any time (including in a service release).
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.
When an API need to be declared deprecated, the contributor has to:
Copyright © 2015 Mia-Software and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v20.html.