| Re: [che-dev] Incompatible API extensions |
|
Hi Gennady, I believe we are in general agreement there.
Since OSGi semantic versioning principles cannot be applied 100% on all parts of Che, we need to differentiate a bit. For the API part, REST services and DTOs are probably most critical. Services should be backward compatible, i.e., older
clients can still work with newer servers. That implies a number of things: ·
URIs shall remain stable, permanent forwarding can be used as a means of deprecation. ·
Hierarchical structure of DTOs shall be preserved. Do not assume a specific ordering of attributes if possible. ·
Renaming or deleting DTO attributes should be the absolute exception. Rather add new attributes while keeping
the old ones for compatibility. Same for rel-links to other resources. ·
Missing attributes in messages from clients assuming an older API version should be gracefully replaced with
defaults if possible, unknown attributes from clients assuming newer API versions should be silently ignored by the server (the latter actually refers already to forward compatibility). For the SPI part we will have to see how frequent such changes occur. As I already outlined, Java interfaces have some
drawbacks if you don’t have full control over your implementors (unless you require Java 8 with default methods). For example, Eclipse used to introduce lots of “IXyz2” interfaces in the early days to prevent breaking existing implementations of IXyz (e.g.,
org.eclipse.ui.IActionDelegate2) and later provided abstract superclasses with empty default implementations for consumer convenience (e.g., org.eclipse.ui.actions.ActionDelegate). This practice is again frowned upon by OSGi purists because of the implied
tighter coupling between interface and implementation. However, in your case I wouldn’t see much harm done if you provided such empty default implementation classes for your DAO and other interfaces… But I am fine with any SPI evolution as you see fit as long as you restrict incompatible interface changes to minor version
upgrades (2nd digit) and keep patch versions compatible (3rd digit). I take it from the discussion that your API/SPI governance so far consists mainly of due diligence, ensured by continuous
code reviews, and that there are no automated tests in place yet, which I might have missed, right? Thanks, Christoph From: che-dev-bounces@xxxxxxxxxxx [mailto:che-dev-bounces@xxxxxxxxxxx]
On Behalf Of Gennady Azarenkov 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. 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:
|