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 >
