[hibernate-dev] Compatibility Considerations wiki

[Steve Ebersole]

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


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
>>>
>>
>>
>