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"

(updated API policy)
Line 1: Line 1:
 
=== API lifecycles and contracts in Xtext ===
 
=== API lifecycles and contracts in Xtext ===
−
We distinguish between technically visible 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 allow that but at the same time communicate clearly which bits stay as is and which might be changed in future releases.
+
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.
  
−
==== @Stable annotation ====
+
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.
−
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 reasonable default implementations or at least throw exceptions, that will be handled by the framework.  
+
−
 
+
−
Example:
+
−
 
+
−
@Stable(since="0.7.0", subClass=AbstractScope.class)
+
−
public interface IScope {
+
−
    ...
+
−
}
+
−
 
+
−
We will not remove any existing method or change its signature without notice. Furthermore their preconditions will not be weakend nor will the postcondition be strengthend. That means, for example, that a method, that never got a null value as an argument, has suddenly to deal with nulls in the next release. If we provide an API, for which the implementor has to fulfil some documented invariants, we will not strengthen them.
+
  
 
==== @Deprecated annotation ====
 
==== @Deprecated annotation ====
−
We also use the @java.lang.Deprecated annotation in order to mark API as deprecated. As for the @Stable annotation, this allows to search for references to this annotation in the Xtext framework code, to identify the parts of the API, that are obsolete. Furthermore, we will document deprecation in the javadoc to inform clients about the necessary steps to remain compatible to future versions.
+
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.
−
 
+
An alternative to the deprecated API is available in those cases.
−
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.
+
  
−
If we remove an interface method, that has been marked as deprectated before, we will leave a method stub with the same signature in the abstract base class. This one will be changed to protected visibility and tagged final to ensure compile time errors for existing clients, that didn't refactor their implementation accordingly.
+
==== General Comment ====
 +
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. 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 05:07, 19 May 2010

API lifecycles and contracts in Xtext

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.

@Deprecated annotation

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. An alternative to the deprecated API is available in those cases.

General Comment

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

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

Back to the top