Skip to main content
Jump to: navigation, search

Difference between revisions of "Xtext/Documentation/API"

(New page: === API lifecycles and contracts in Xtext === We distinguish between the technical visibility and published API. That means not everything which is technically visible is considered as pub...)
 
(Binary but not source compatibility)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=== API lifecycles and contracts in Xtext ===
+
=== Binary but not source compatibility ===
We distinguish between the technical visibility and published API. That means not everything which is technically visible is considered as published or stable API. We have lot's of useful things you may want to use, and we think it's important to communicate which bits you can savely use and which might be changed in future releases.
+
  
==== @Stable annotation ====
+
Xtext versions with minor increments are '''binary compatible''' with early releases of the same major version
In order to communicate what's stable, we tag interfaces and classes with the annotation @org.eclipse.xtext.Stable.
+
  
In most cases we follow a common pattern, where we tag an interface with @Stable and add a pointer to the abstract class you need to subClass in order to be sure that we don't break your code in future releases. This is because we might want to add additional methods to those interfaces, as long as you also subclass a common base class, we can provide default implementations.
+
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 guaranteed source compatible.
  
Example:
+
Only if the major version increments API might be removed, replaced or changed in *binary incompatible* ways.
 
+
@Stable(since="0.7.0", subClass=AbstractScope.class)
+
public interface IScope {
+
    ...
+
}
+
 
+
==== @Deprecated annotation ====
+
We also use the @java.lang.Deprecated annotation in order to mark API as deprecated.
+
If a stable API is annotated with @Deprecated it means that we might remove it in the next major release.
+
This means that if stable API is annotated with @Deprecated in 0.7.0 it will remain in 0.x but might be removed in 1.x releases.
+

Latest revision as of 07:11, 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 guaranteed source compatible.

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

Back to the top