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 18:02:57 GMT
I went ahead and submitted this as CURATOR-193. If folks have a
clarification on what the semver use is supposed to cover, I'll file
another ticket to get that documented.

On Wed, Mar 11, 2015 at 12:50 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
>> >
>>
>


-- 
Sean

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