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 ([email protected]) 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" <[email protected]> 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 <[email protected]> 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 < > > [email protected] > > > 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 ([email protected]) > 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 > > >
