Jump to: navigation, search

Difference between revisions of "MoDisco/API Policy"

(Deprecated API may not be removed for at least 1 major release in place of 2 major releases)
(Deprecated API declaration)
 
(15 intermediate revisions by 5 users not shown)
Line 5: Line 5:
 
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.  
 
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.  
  
= <br> Declared API  =
+
== 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.  
 
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 releases (and preferably longer), and after notifying the community.  
+
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.
  
= <br> Provisional API  =
+
== 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 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.  
Line 21: Line 21:
 
*/
 
*/
 
</pre>  
 
</pre>  
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 should be marked as provisional accordingly to the ecore definition. Provisional Extension Point API should be marked as “incubation” in extension point naming.  
+
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.
  
= <br> Examples API  =
+
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.  
 
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.  
+
Any resource included in a plugin whose name indicates 'examples' should be considered of Example API kind.
  
= <br> Internal Use  =
+
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.  
 
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).  
+
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.''
  
Extension points should be indicated by 'internal' in extension point name.  
+
Internal extension points should be indicated by 'internal' in the extension point name.  
  
Model internal API (rare) should be indicated by ‘internal’ in identifier.  
+
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.
 
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.
 +
 +
{{MoDisco}}
 +
[[Category:MoDisco]]

Latest 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.


MoDisco
Components Infrastructure: KDM · SMM · GASTM · Model Browser · Discovery Manager · MoDisco Workflow · Query Manager · Facet Manager · Metrics Visualization Builder · KDM Source Extension
Technologies: Java · JEE · EjbJar · WebApp · XML
Use Cases: Simple Transformation Chain · Model Filter
Help Installation · SVN
Project API Policy · Retention Policy · Project Plan · metrics · Accessibility Guidelines · Capabilities Disablement