Java API breakage on .ecore change for EMF-related bundles: what is SimRel policy?

[ruspl-afed]

It seems that almost every change in .ecore may break API according to API rules and will require major version increment for "model" bundle that contains generated Java API

For example, if we add a transient EAttribute to any EClass it is a kind of transparent for EMF persistence and may be considered as a minor change for .ecore, however formally it requires major version increment.

Another example: we add a Classifier to ecore, and changing (incrementing version) NS URI to distinguish models created with newer version: from API point of view we need major bump for many reasons. One of them is changed value of String eNS_URI constant in *Package class. Many others follow, because we have a lot of new fields and methods.

What is the current policy for this in the scope of SimRel @merks ?

[merks]

The API tools are ultra conservative. Add anything to an interface and it's a major version increment. The Platform makes a habit of being careful and suppressing such API errors, e.g., when adding a default method to an interface or a constant to SWT.

Of course constants are in-lined so changing that will not be seen by clients who aren't recompiled. The GenModel property `Binary compatible Reflective Methods" can help make derived models binary compatible even if the super class model changes. There is no general policy about this. In my opinion, it's better to simply be pragmatic and try to have as little impact on clients as possible. Major version increments generally cause problems and the more bundles that are downstream from the incremented bundle, the more problems it causes.

I've never felt compelled to change the nsURI of a model. It seems to me that that approach generally causes more problems than it prevents. Options like org.eclipse.emf.ecore.xmi.XMLResource.OPTION_RECORD_UNKNOWN_FEATURE are very useful for being able to read a newer model instance with an older implementation and still preserve the unrecognized information.

[ruspl-afed]

Thank you for your reply @merks and for GenModel hint.

The Platform's policy here is really very ambiguous: with such strict rules, they have plenty of exceptions to get around them and do not increment major version for Platform bundles.

There is no general policy about this. In my opinion, it's better to simply be pragmatic and try to have as little impact on clients as possible. Major version increments generally cause problems and the more bundles that are downstream from the incremented bundle, the more problems it causes.

Let this be the answer for now.

It seems to me that that approach generally causes more problems than it prevents.

We have a usage example where different versions of a product (let's say V1 and V2) are used in the same user space with potential to work with the same set of models (and we can't change that, because in the case of application programming, users are always smarter).

If V1 opens a model from V2 to modify and save it - we have a risk to silently loose data, that exists only in V2. This is why we prefer to report problem fast instead of doing post-mortem investigations when and what was silently discarded.
In addition we have powerful migration framework to auto-upgrade V1 to V2 during load and also UI actions like "Save As V1"

[ruspl-afed]

The API tools are ultra conservative. Add anything to an interface and it's a major version increment. The Platform makes a habit of being careful and suppressing such API errors

Eclipse Passage formulated the following statement in its policy:

Eclipse Passage project does not fully follow Eclipse Platform's rules until Eclipse Platform project fully follows these rules itself.

[HannesWell]

As far as I know every Eclipse project can define its own versioning rules, e.g. in M2E we don't refer to the platform policy (I'm not sure if we even have it defined explicitly or just do SemVer). But regardless of the rules defined and followed, binary-incompatible/breaking changes are always annoying for downstream consumers and one should always be cautious with them.
E.g. when we created a clean M2E 2.0 release there were still complaints about these breaking changes.

Following SemVer does not generally solve that problem, it just makes it more manageable and simpler to understand and also makes the applicable version-ranges predictable.

And the current two year depreciation period used in the SDK, at least gives timely predictability.

Btw. since you want to really follow SemVer rules, you should actually not increment versions of a bundle if it wasn't changed for that release, just to align all project versions.