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 <[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 >> > >> > -- Sean
