Re: [hibernate-dev] Compatibility Considerations wiki

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