[hibernate-dev] Compatibility Considerations wiki

[Gunnar Morling]

2014-08-25 18:33 GMT+02:00 Steve Ebersole <steve at hibernate.org>:

> On Mon, Aug 18, 2014 at 2:14 AM, Gunnar Morling <gunnar at hibernate.org>
> wrote:
>
>> Hi Steve,
>>
>> Thanks for writing up these rules. That's very valuable information for
>> users and us as well.
>>
>> Only two remarks on the following:
>>
>> > The use of package names for this is unfortunately not granular enough
>> oftentimes.
>> > Ultimately I would envision a better solution (annotations?)
>>
>> In which cases is it not granular enough? Can such case not always be
>> circumvented by refactoring code into separate classes within separate
>> packages?
>>
>> I'm fearing issues with e.g. distinguishing between public (API/SPI) vs.
>> internal parts on a finer level than the package, as that's what OSGi but
>> also JBoss Modules rely on. We cannot fully leverage the ability of these
>> module systems to "hide" internal parts of a module in that case.
>>
>> Also I think annotations are easier to "miss" than package names when
>> importing classes into an application, thus I'm concerned about accidental
>> referencing internal classes.
>>
>
> To be honest I don't remember the situations I have run into that brought
> me to that conclusion.
>

Hard to argue against that :) I think what troubles me that the information
about public/private is "one step farther away".

E.g. when examining a client program which imports stuff from a package
with "internal" in its name, this flaw is easily detectable just by looking
at the program. Whereas with an annotation-based approach, you need to look
at the imported types themselves to learn about any un-wanted imports in
the client program.

> SPI contracts should be considered stable within a release family, not
>> necessarily across different release families.
>>
>> A specific example, similar to the API section, would be nice, e.g.: "If
>> you implement an application against an integration point from Hibernate
>> ORM 4.3.0, the expectation is that it works without changes when updating
>> to ORM 4.3.1. It should also continue to work when updating to ORM 4.4.x in
>> the very most cases, but that's not guaranteed."
>>
>
> Actually the 4.3 -> 4.4 bit here is not really accurate, and illustrates
> the main difference between an API and an SPI.  Most of the time, yes,
> using an SPI method from 4.3 and upgrading to 4.4 will work flawlessly.
>  But that is in no way by design; it just means that it worked by
> happenstance.
>

Really, it's not by design? I'd expect that we work hard to also keep SPIs
backwards-compatible, that we don't break them easily but only if it's
there is no reasonable way around it.


>  Which is fine for SPI use from applications, but I think explains why we
> often run into problems with upgrades to ORM in regards to other Hibernate
> projects, since the Hibernate projects tend to use a high number of these
> SPIs.  This would also be good to discuss.
>
>
>