[hibernate-dev] Compatibility Considerations wiki

[Steve Ebersole]

That should read "API contracts should be considered stable within all
releases within a major version".  As an example, an application developer
should be able to develop against APIs as available in 4.2 and be able to
drop 4.3 into that application without changes, so long as they rely only
on defined APIs.

This is what is called backwards compatibility: meaning that any changes
done in 4.3 are done in such a way as to remain compatible with older
(backward) versions.  Personally, I find the terms confusing because I
think of it in terms of "porting" the application forward to use a newer
version of a library.

The inverse is something we actually do not guarantee in regards to APIs
and going back to an older version (reverting).  An example here would be
developing an application using the natural-id API developed in 4.2 and
then trying to port that application to use 4.1.  That won't work.

So within a major version we guarantee APIs to be backwards compatible, but
not forward compatible.

Does that wording help clarify?



On Wed, Aug 13, 2014 at 9:32 AM, Sanne Grinovero <sanne at hibernate.org>
wrote:

> Thanks Steve!
> that's extremely useful.
>
> My only doubt is the relation between release families, quoting:
>  >> Hibernate considers the {major}.{minor} combination a release "family".
>
> and then later below in paragraph "The rules" :
>  >>  API contracts should be considered stable across all releases in a
> family.
>
> I'm not sure if you mean that 4.4.0 and 4.4.1 are (promised to be) API
> compatible, while 4.3.0 and 4.4.0 are not..
> I would say from the definition above that I should not expect that as
> the two are in a different family, still the following example seems
> to point out that any 4.x will be drop-in compatible with 4.0.0 ?
>
> It would also help to understand the rules better to explain when the
> team decides to bump the major version.
>
> Sanne
>
>
> On 9 August 2014 15:55, Steve Ebersole <steve at hibernate.org> wrote:
> > 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
>