curator-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jordan Zimmerman <jor...@jordanzimmerman.com>
Subject Re: Is Curator's semver over binary or source compatibility?
Date Wed, 11 Mar 2015 18:49:43 GMT
We’ve never codified this in any way. This would be a TBD.

-Jordan



On March 11, 2015 at 12:51:31 PM, Sean Busbey (busbey@cloudera.com) wrote:

Can you point me to docs on what's in the public API?  

All I could find was a description of when folks would want to use  
framework, client, and recipes. That implied, to me, that they were all  
public API.  

--  
Sean  
On Mar 11, 2015 12:37 PM, "Mike Drob" <mdrob@apache.org> wrote:  

> I believe the public API is defined as things in o.a.c.framework.api  
> package. Not sure what our stance on recipes is.  
>  
> On Tue, Mar 10, 2015 at 12:43 AM, Sean Busbey <busbey@cloudera.com> wrote:  
>  
> > I'm trying to figure out what sense of "use" is meant in that quote. Is  
> it  
> > safe to assume it means "all of the above"?  
> >  
> > I ask because in anticipation of a dependency update, I ran 2.6.0 and  
> 2.7.1  
> > through the Java API Compliance Checker[1], and I'm trying to figure out  
> > which (if any) of the following things I should file as bugs.  
> >  
> > # org.apache.curator.utils.PathUtils.validatePath(String) in  
> curator-client  
> >  
> > In release 2.7.0, CURATOR-136 changed the return type of this method from  
> > void to String. This is fine for a semver minor version under source  
> > compatibility, but is a violation of semver under binary compatibility. A  
> > downstream user will get NoSuchMethodError if their already compiled  
> class  
> > uses this method.  
> >  
> > Note that changing it back will also be a breaking change, because the  
> Java  
> > language gives you no means to have two methods that only differ by  
> return  
> > type[3]. I think that means the fix for this problem is updating release  
> > notes (or an upgrade guide or a FAQ depending on what else the community  
> > already has).  
> >  
> > #  
> >  
> >  
> org.apache.curator.framework.recipes.shared.SharedCountReader.getVersionedValue()  
> > in curator-recipes  
> > #  
> >  
> >  
> org.apache.curator.framework.recipes.shared.SharedValueReader.getVersionedValue()  
> > in curator-recipes  
> >  
> > In release 2.7.0, I think CURATOR-151 added these two methods to these  
> > interfaces as a part of improving an API.  
> >  
> > The changes are fine for binary compatibility provided nothing in the  
> > framework ever calls them (doing so will result in NoSuchMethodError when  
> > called on an instance compiled against the older interface). AFAICT,  
> > nothing in the framework accepts one of these interfaces and then calls  
> > this method.  
> >  
> > However, the addition of methods to Java interfaces breaks source  
> > compatibility. The inter-process semaphore recipes work on arbitrary  
> > SharedCountReader instances. That means that downstream folks who made  
> > their own implementation of the SharedCountReader interface under 2.6.0  
> > will get a compilation error when they attempt to update to 2.7.0+.  
> >  
> > Removing either of these methods would be a breaking change under both  
> > binary and source compatibility, so if source compatibility is desired  
> the  
> > fix in this case is likely the same as the PathUtils problem above.  
> >  
> > [1]: http://ispras.linuxbase.org/index.php/Java_API_Compliance_Checker  
> > [2]:  
> >  
> >  
> http://people.apache.org/~busbey/compat_reports/curator/2.6.0_to_2.7.1/compat_report.html
 
> > [3]: the JVM allows it, so some hijinks could get you a jar file that  
> > didn't break binary compatibility with either 2.6 or 2.7, but it's a  
> > terrible idea.  
> >  
> > On Mon, Mar 9, 2015 at 7:06 PM, Jordan Zimmerman <  
> > jordan@jordanzimmerman.com  
> > > wrote:  
> >  
> > > The comment from Eric explains how we use it:  
> > >  
> > > Essentially, it tells you the API compatibility between multiple  
> > > dependencies. For example,  
> > >  
> > > If you have version 1.0.0 and 1.0.1, you can use either one and you  
> will  
> > > not run into errors due to API conflicts (i.e. in Java, no  
> ClassNotFound  
> > or  
> > > NoSuchMethod type exceptions)  
> > >  
> > > If you have 1.0.0 and 1.1.0, you can replace 1.0.0 with 1.1.0 and you  
> > will  
> > > not have errors due to API conflicts. If you try to swap 1.0.0 in place  
> > of  
> > > something that depends on 1.1.0, however, you *might* have errors due  
> to  
> > > API conflicts. I.e. you can go forward without errors, but not  
> backwards  
> > >  
> > > If you have 1.0.0 and 2.0.0, you will likely have errors due to API  
> > > conflicts if you replace either one with the other.  
> > >  
> > >  
> > >  
> > > On March 9, 2015 at 6:18:16 PM, Sean Busbey (busbey@cloudera.com)  
> wrote:  
> > >  
> > > Hi!  
> > >  
> > > I'm very happy to see that Curator has adopted semver[1].  
> > >  
> > > A couple of things that aren't immediately obvious:  
> > >  
> > > 1) Is the semver promise over binary compatibility, source  
> compatibility,  
> > > behavior compatibility or some combination thereof?  
> > >  
> > > 2) Is the semver promise over all public/protected things in all the  
> > > published artifacts, or just some subset (e.g. just curator-client or  
> > > curator-recipes, or some set of packages)?  
> > >  
> > > [1]:  
> > >  
> > >  
> >  
> https://cwiki.apache.org/confluence/display/CURATOR/For+Curator+Committers#ForCuratorCommitters-versioning
 
> > >  
> > > --  
> > > Sean  
> > >  
> > >  
> >  
> >  
> > --  
> > Sean  
> >  
>  

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message