Jump to: navigation, search

Difference between revisions of "Acceleo/API Policy"

(Internal API)
(Internal API)
Line 11: Line 11:
 
Any class that is not located in an exported package or is declared as "private" or "package" is considered internal. Non API classes are usually located in a package named "internal". Internal API may and will be modified at any time, without prior notice. We also use API Tooling specific javadoc tags in order to enforce "internal" aspects on some of the Declared API classes, "@noImplements", "@noExtends", "@noOverrides", etc... denote interface, classes and methods on which some aspects are not authorized by the team and may be broken without notice.
 
Any class that is not located in an exported package or is declared as "private" or "package" is considered internal. Non API classes are usually located in a package named "internal". Internal API may and will be modified at any time, without prior notice. We also use API Tooling specific javadoc tags in order to enforce "internal" aspects on some of the Declared API classes, "@noImplements", "@noExtends", "@noOverrides", etc... denote interface, classes and methods on which some aspects are not authorized by the team and may be broken without notice.
  
Take note that generated classes and interfaces, though not tagged as "@noImplements" or "@noExtends" are still considered as such and *should never be subclassed or implemented; we may add methods to these interfaces without prior notice.
+
Take note that generated classes and interfaces, though not tagged as "@noImplements" or "@noExtends" are still considered as such and '''should never be subclassed or implemented'''; we may add methods to these interfaces without prior notice.
  
 
Adopters requiring the use of internal code should open bugzilla enhancement requests for API. These bugs will be analyzed and will help drive the creation of new API when possible.
 
Adopters requiring the use of internal code should open bugzilla enhancement requests for API. These bugs will be analyzed and will help drive the creation of new API when possible.

Revision as of 03:52, 9 August 2010

Acceleo API Policy

Declared API

Declared API is public API that the Acceleo team will support for the time being. It is comprised of every class/interface declared "public" and contained in an exported package.

In subsequent releases, declared API may sometimes be deprecated due to the normal evolution of the project. Deprecated methods will always be appropriately commented with information on how to accomplish the same with either existing or new API methods. Deprecated API will not be removed from the codebase until the next major release, and even major releases may see deprecated API maintained. In any event, the community will be notified of the deletion of any deprecated API through the usual communications channels (newsgroup, mailing list, etc).

API compatibility will be maintained through each and every release. API breakages will always go through a phase of deprecation that will last until the next major release at a bare minimum, and suppression of deprecated API will always be notified at least before the M6 milestone of this next major release.

Internal API

Any class that is not located in an exported package or is declared as "private" or "package" is considered internal. Non API classes are usually located in a package named "internal". Internal API may and will be modified at any time, without prior notice. We also use API Tooling specific javadoc tags in order to enforce "internal" aspects on some of the Declared API classes, "@noImplements", "@noExtends", "@noOverrides", etc... denote interface, classes and methods on which some aspects are not authorized by the team and may be broken without notice.

Take note that generated classes and interfaces, though not tagged as "@noImplements" or "@noExtends" are still considered as such and should never be subclassed or implemented; we may add methods to these interfaces without prior notice.

Adopters requiring the use of internal code should open bugzilla enhancement requests for API. These bugs will be analyzed and will help drive the creation of new API when possible.