[hibernate-dev] Compatibility Considerations wiki

[Sanne Grinovero]

in an ideal world, absolutely, and I didn't mean that annotations
should be a replacement for correct package choices.
Having the "right" annotations mature over time might also be a great
help to define how to exactly move things when you're allowed to break
things.

Just that reality has proven that we need more flexibility, especially
in things like ORM were the community is extremely large, from
tooling, IDE support and even most Java profilers nowadays have
special support for Hibernate, and will probably do "special things"
beyond API.
I'd guess that any fix in ORM makes some stuff break somewhere in the
world, so anything which can help us redefine and adjust these
boundaries without moving packages is welcome.

Cheers,
Sanne


On 18 August 2014 13:13, Gunnar Morling <gunnar at hibernate.org> wrote:
> 2014-08-18 13:12 GMT+02:00 Sanne Grinovero <sanne at hibernate.org>:
>
>> 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.
>
>
> Yes, it's not so much about mixing API/SPI types in one package (maybe there
> is even an overlap in some cases) but it's public (i.e. API + SPI) vs.
> internal parts which I don't think should be in one package.
>
>>
>> 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.
>
>
> But shouldn't you really know about that nature of an exposed type after a
> Beta phase? There is still the possibility to mark API/SPI members as
> incubating (we have an annotation @Experimental for this in OGM, not sure
> about others) if it's something still evolving. And the document reserves
> the right to fix "errors" anyways.
>>
>>
>> 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.
>
>
> Agreed on SPI (see above), but is there really a problem with moving an
> accidentally exposed type to an "impl" package? It has not been designed to
> be accessed publicly, so ideally there should be no public users anyways.
> But if there are and we want to avoid breaking them, then it's actually a
> public contract by its nature and it should be maintained, no?
>
> To me, something is either public (then we need to keep compatibility in
> mind when changing it) or its internal (then we can change it as we like),
> but I don't think there is something in between. Having an internal type
> which we cannot touch seems like a paradox to me.
>
>> If your goal is to publish a nice set of javadocs for users which has
>> API only, annotations would allow to do this.
>
>
> It's more the public vs. private API distinction of e.g. OSGi I have in mind
> and its way for making sure only public parts are ever consumed by clients.
>
>> 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
>
>