Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Xtext/Documentation/API"

(→‎General Comment)
(updated API policy)
Line 1: Line 1:
−
=== API lifecycles and contracts in Xtext ===
+
=== Binary but not source Compatibility ===
−
Xtext is designed to be very flexible and extendable. We do not believe that we should hinder users from using or extend certain code technically but prefer to communicate what to expect. In Xtext we have two different kinds of API: public API and provisional API. Every class or interface which is explicitly documented in the current release's documentation or is used in one of the examples is considered to be public API and will be binary compatible for each major version. This includes all releases as well as all release candidates and the milestones M6 and M7.
+
  
−
However compatibility is not guaranteed between major versions. We generally try to find a good compromise between breaking clients and cleaning up concepts and we carefully think about incompatible changes. That is if we think the improvements in the code base are important enough compared to the migration effort we decide to change such API. Again, this is only the case for major version increments. We won't change any public API in minor increments.
+
Xtext versions with minor increments are *binary compatible* with early releases of the same major version
  
−
==== @Deprecated annotation ====
+
That is you will be able to run any code, which was developed *and compiled* against API from 2.x with any 2.y (where y>=x) version. However you might run into compatibility problems
−
We also use the @java.lang.Deprecated annotation in order to mark API as deprecated. That is only to inform you that we will most likely remove that API in the next major version.
+
if you try to compile or even regenerate source code which was developed against a previous version, because only micro increments (i.e. 2.x.y -> 2.x.z , where z >= y ) are also source compatible.
−
An alternative to the deprecated API is available in those cases.
+
  
−
==== General Comment ====
+
Only if the major version increments API might be removed, replaced or changed in *binary incompatible* ways.
−
We are aware that this is a rather weak definition of an API contract. We think the more mature the framework gets the less API will be changed from version to version and we might be able to come up with a better assurance. However as the project is relatively young and we can't put much resources in keeping an maintaing old (wrong) API we think this policy is accurate.
+

Revision as of 07:04, 30 January 2012

Binary but not source Compatibility

Xtext versions with minor increments are *binary compatible* with early releases of the same major version

That is you will be able to run any code, which was developed *and compiled* against API from 2.x with any 2.y (where y>=x) version. However you might run into compatibility problems if you try to compile or even regenerate source code which was developed against a previous version, because only micro increments (i.e. 2.x.y -> 2.x.z , where z >= y ) are also source compatible.

Only if the major version increments API might be removed, replaced or changed in *binary incompatible* ways.

Retrieved from "https://wiki.eclipse.org/index.php?title=Xtext/Documentation/API&oldid=287342"

Back to the top