Re: [che-dev] Incompatible API extensions

[Gennady Azarenkov <gazarenkov@xxxxxxxxxxx>]

Hi Christoph,

Indeed, it is 2 levels and DAO is rather internal interfaces (SPI) while REST API and all the transport objects are external API.

What level of compatibility we suppose to have now?

My vision is that we have to be rather flexible here, it is always the compromise between current state of project "stability" (in the other words freedom of core developers) and potential implementors issues (ones who follow our front version).

So, I would say for the time being:

- we should consider as a REALLY special case lost of backward compatibility on API level between minor versions. I.e. we try to do our best to avoid any incompatibility in REST API, DTO etc and we must warn contributors and deprecate "old" things for some time (maybe 1 or 2 intermediate versions) before replace it. 
- we basically do not consider any compatibility limitations for SPI level. I.e. we do our best to inform, discuss those things (well, not always but will try :) ) but do not postpone to release those changes. Well, we try to be reasonable here, for instance adding method to SPI (like we have now) is probably not the same sensitive change as changing method signature.

When our API/SPI become more "mature" we make the policy more strict.  

Does that make sense for you?

 

Gennady Azarenkov - CTO @ codenvy.com

On Fri, Apr 17, 2015 at 2:30 PM, Pohl, Christoph <christoph.pohl@xxxxxxx> wrote:

Thanks, Sergii!

 

Just to relate my previous post a bit: For semantic versioning it also makes sense to differentiate between API and SPI (consumer vs. provider interfaces). For SPI it is OK to introduce new features in minor versions. You could argue that WorkspaceDao is rather SPI than API (like all *Dao’s).

 

Nevertheless, it would be interesting if you have some sort of API governance in place yet. I was wondering if there were any means for that at all outside of the OSGi world…

 

Best,

Christoph

 

From: che-dev-bounces@xxxxxxxxxxx [mailto:che-dev-bounces@xxxxxxxxxxx] On Behalf Of Sergii Kabashniuk
Sent: Freitag, 17. April 2015 10:20
To: che developer discussions
Subject: Re: [che-dev] Incompatible API extensions

 

Hello Christoph.

 

Thank you for pointing us to this issue.

In the next few days we will investigate it and let you know.

 

Sergii Kabashniuk

 

On Fri, Apr 17, 2015 at 10:46 AM, Pohl, Christoph <christoph.pohl@xxxxxxx> wrote:

Hi folks,

 

not sure if you are aware of this…

 

With https://github.com/codenvy/che-core/commit/e3a19a15fa7b58eec3ef5ceab22a8a4b8eff69af you recently introduced in 3.9 an incompatible API extension to interface WorkspaceDao in the form of a new method.

 

Introducing new methods in API interfaces is actually not permitted in minor release upgrades like 3.8->3.9 because you will immediately break all external 3.8-based implementors. There are implementors out there besides your LocalWorkspaceDaoImpl, which are not part of your code base.
The usual way to go in such situations would be to introduce an abstract superclass in your API, which implementor can extend compatibly instead of implementing the interfaces directly.

See also http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf

 

Do you have some sort of API baseline checks in place like Eclipse PDE used to provide?

 

Cheers,

Christoph

 

_______________________________________________
che-dev mailing list
che-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/che-dev

 

_______________________________________________
che-dev mailing list
che-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/che-dev