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.
Xtext/Documentation/API
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.