> Hibernate considers the {major}.{minor} combination a release "family".

> API contracts should be considered stable across all releases in a family.

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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

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(a)hibernate.org&gt; 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(a)hibernate.org&gt; 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(a)lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >

The use of package names for this is unfortunately not granular enough

Ultimately I would envision a better solution (annotations?)

SPI contracts should be considered stable within a release family, not

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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

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.

API only, annotations would allow to do this.

On 18 August 2014 08:14, Gunnar Morling <gunnar(a)hibernate.org&gt; 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(a)hibernate.org&gt;: > >> 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(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev

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(a)hibernate.org&gt; 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(a)hibernate.org&gt;: > >> 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(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

On 25 Jan 2014, at 18:37, Steve Ebersole <steve(a)hibernate.org&gt; wrote: > This is all certainly true. I think specifically of things like > persisters, which by "package break down" are currently considered API. > > 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. I agree that the generation of the OSGi metadata via annotation would not be such a big problem, however, OSGi does afaik not allow to configure modules on a class level. The fines granularity on what is exported is on package level. Just saying.

—Hardy _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

2014-08-25 18:37 GMT+02:00 Steve Ebersole <steve(a)hibernate.org&gt;: 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(a)hibernate.org&gt; > 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(a)hibernate.org&gt; 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(a)hibernate.org&gt;: >> > >> >> 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(a)lists.jboss.org >> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> >> >> > _______________________________________________ >> > hibernate-dev mailing list >> > hibernate-dev(a)lists.jboss.org >> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >> _______________________________________________ >> hibernate-dev mailing list >> hibernate-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > >

2014-08-27 7:15 GMT+02:00 Steve Ebersole <steve(a)hibernate.org&gt;: 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(a)hibernate.org&gt; > wrote: > >> 2014-08-25 18:37 GMT+02:00 Steve Ebersole <steve(a)hibernate.org&gt;: >> >> 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(a)hibernate.org&gt; >>> 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(a)hibernate.org&gt; 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(a)hibernate.org&gt;: >>>> > >>>> >> 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(a)lists.jboss.org >>>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>>> >> >>>> > _______________________________________________ >>>> > hibernate-dev mailing list >>>> > hibernate-dev(a)lists.jboss.org >>>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>>> _______________________________________________ >>>> hibernate-dev mailing list >>>> hibernate-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>>> >>> >>> >> >

2014-08-28 0:52 GMT+02:00 Steve Ebersole <steve(a)hibernate.org&gt;: > You have to admit that moving everything (again in this singular example) > from org.hibernate.persister to a whole package would be extremely > disruptive to OGM, et al. Yes? Yes, it would be disruptive. As said though, I personally would not not be that annoyed about a package re-organization as it something I can quite easily adapt to. Changed semantics of an API/SPI which require me to actually re-program large parts of my application/integration would be more scary. Generally I think users (or integrators) are understanding about incompatible changes in a major release, if there is a significant value to these changes and they are not done for the fun of it. So it really boils down to your question below whether we deem an api/spi/internal structure worth it or not. > > So yes, making these changes is allowable under the rules laid out. But > that does not mean we run out ad try to screw over integrations :) We still > strive to maintain compatibility for SPIs as well as APIs. Ok, that's good. The "But that is in no way by design; it just means that it worked by happenstance" from before had me scared a bit :) > > I think the relative question here is whether breaking these into > api/spi/internal package structure (for OSGi, intention documentation > purposes) alone warrants completely breaking compatibility with all > integrations. I'd tend to vote no. I understand and I'd tend to agree for SPIs. My point was more about parts considered internal where I don't see why they couldn't be moved, because backwards-compatibility shouldn't be relevant there. To sum it up, I'd be concerned about using annotations (rather than packages) for marking parts as internal due to the reasons outlined before, whereas using annotations for marking parts as SPI may be a good middle-ground. > On Wed, Aug 27, 2014 at 1:20 AM, Gunnar Morling <gunnar(a)hibernate.org&gt; > wrote: >> >> 2014-08-27 7:15 GMT+02:00 Steve Ebersole <steve(a)hibernate.org&gt;: >> >>> 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(a)hibernate.org&gt; >>> wrote: >>>> >>>> 2014-08-25 18:37 GMT+02:00 Steve Ebersole <steve(a)hibernate.org&gt;: >>>> >>>>> 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(a)hibernate.org&gt; >>>>> 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(a)hibernate.org&gt; 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(a)hibernate.org&gt;: >>>>>> > >>>>>> >> 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(a)lists.jboss.org >>>>>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>>>>> >> >>>>>> > _______________________________________________ >>>>>> > hibernate-dev mailing list >>>>>> > hibernate-dev(a)lists.jboss.org >>>>>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>>>>> _______________________________________________ >>>>>> hibernate-dev mailing list >>>>>> hibernate-dev(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>>>> >>>>> >>>> >>> >> >

On Mon, Aug 18, 2014 at 2:14 AM, Gunnar Morling <gunnar(a)hibernate.org&gt; 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.

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.

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.

Awesome write up. I will for sure steal a lot of it :) A few random comments: - once we are sufficiently happy, we probably should move this to the website

- you mention backward compatibility and leave aside source vs binary backward compatibility. Do we want to dive on this subject? The later is of course much harder even though relatively well defined for Java.

Emmanuel On Sat 2014-08-09 9:55, Steve Ebersole 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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev