curator-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sean Busbey <bus...@cloudera.com>
Subject Re: Is Curator's semver over binary or source compatibility?
Date Wed, 11 Mar 2015 17:50:18 GMT
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