[hibernate-dev] Compatibility Considerations wiki

Wed Aug 27 02:20:38 EDT 2014

2014-08-27 7:15 GMT+02:00 Steve Ebersole <steve at hibernate.org>:

> They are an SPI.  I'd break many Hibernate projects and third-party
> integrations if I just moved them...
>

Yes, it would break client code using these SPIs, but isn't such breakage
covered by the rules you laid out before? You even allowed for breaking SPI
changes between minor release families (from 4.3 to 4.4), so such a
re-organization should be acceptable for a major release such as 5?

Or are you saying that there is a category of changes which is "too big"
and thus never can be done? As a library user I personally can say that I'd
be ok with this sort of changes in a major upgrade, in particular if its as
easy to adapt to as just importing (otherwise un-altered) types from other
packages.

Btw. what are the rules/expectations for API changes in a major version
(5), are breaking changes allowed there? The document only seems to
describe changes within a release family ("API contracts should be
considered stable across all releases within a major version (3.x or 4.x,
etc)").

>
> On Tue, Aug 26, 2014 at 1:34 AM, Gunnar Morling <gunnar at hibernate.org>
> wrote:
>
>> 2014-08-25 18:37 GMT+02:00 Steve Ebersole <steve at hibernate.org>:
>>
>> This is all certainly true.  I think specifically of things like
>>> persisters, which by "package break down" are currently considered API.
>>>
>>
>> That's a good example. You say based on their package they are considered
>> API, but is that what you actually want for these types? Or, if these types
>> actually should not be considered an API, why can't they be moved?
>>
>> If it's about not wanting to break existing users, I'd say then either a)
>> these types actually *are* an API (why otherwise would we care about
>> backwards compatibility with clients) or b) I wouldn't care about the
>> breakage (in a major release such as 5) because clients should not have
>> used those actually internal parts to begin with. Maybe the fact that those
>> parts are internal was not communicated clearly enough, but a major release
>> seems like the right occasion to fix this then.
>>
>> Also, as far as OSGi, I would suggest not worrying about that so much
>>> (Gunnar).  Keep in mind that even today this OSGi manifest info is
>>> generated by build logic.  Changing that build logic to look at annotations
>>> rather that parsing .class file path is not that big of a deal imo.
>>>  Devil's-in-the-details of course, but in theory it should not be a big
>>> deal.
>>>
>>>
>>> On Mon, Aug 18, 2014 at 6:12 AM, Sanne Grinovero <sanne at hibernate.org>
>>> wrote:
>>>
>>>> I won't speak for Steve's reasons, but I agree with the granularity
>>>> problem.
>>>>
>>>> For example you might not want to refactor the code to promote an SPI
>>>> to API (or simply fix a mistake), or viceversa demote an API to SPI,
>>>> as you moving the packages around would break backwards compatibility.
>>>> Essentially this means you can only fix the packages in that short
>>>> time in which you're in Alpha/Beta phase for a new major release,
>>>> which is a short period in which usually the team has other
>>>> priorities.
>>>>
>>>> The best example is ORM itself in it's current shape: we all know that
>>>> some classes should be moved into SPI or Impl, but we can't touch
>>>> them.
>>>> If your goal is to publish a nice set of javadocs for users which has
>>>> API only, annotations would allow to do this.
>>>>
>>>> Sanne
>>>>
>>>>
>>>> On 18 August 2014 08:14, 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.
>>>> >
>>>> >> 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."
>>>> >
>>>> > --Gunnar
>>>> >
>>>> >
>>>> > 2014-08-09 16:55 GMT+02:00 Steve Ebersole <steve at hibernate.org>:
>>>> >
>>>> >> There was a discussion in regards to our view on backwards
>>>> compatibility in
>>>> >> reference to HHH-9316.  I realized that we talk about this amongst
>>>> >> ourselves, but that I have never written these down.  So I did that:
>>>> >>
>>>> >>
>>>> >>
>>>> https://github.com/hibernate/hibernate-orm/wiki/Compatibility-Considerations
>>>> >>
>>>> >> This is a first draft.  Let me know what you think.
>>>> >> _______________________________________________
>>>> >> hibernate-dev mailing list
>>>> >> hibernate-dev at lists.jboss.org
>>>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>> >>
>>>> > _______________________________________________
>>>> > hibernate-dev mailing list
>>>> > hibernate-dev at lists.jboss.org
>>>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>> _______________________________________________
>>>> hibernate-dev mailing list
>>>> hibernate-dev at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>>
>>>
>>>
>>
>