Hi, I would not make it too academic. Next, I would differ between binary and lowlevel API compatibility on one side and other features on the other.
Have fun, JensG ________________________________ Von: Aki Sukegawa Gesendet: 13.01.2016 13:00 An: dev@thrift.apache.org Betreff: Re: Thoughts on a 0.9.4 rc > the concept of a public "API" for Thrift is multifaceted Indeed. I would categorize them by type of usages: 1. RPC users: use/implement generated service 2. serialization users: use generated struct (e.g. with Kafka) 3. advanced serialization users: directly call protocol write/readXxx (e.g. projects like Parquet or scrooge) > if change in the PHP lib mandates rolling over the version number It seems unavoidable. Alternatives like version-per-language+layer is complicated in practice. Another point to consider is cross version compatibility breaks for minor/patch releases: A. cross version generated code and library B. cross version client and server IMO A. is safely allowed but B. is a major version bump. Because normally A. only needs rebuild on a single host but B. needs coordinated upgrade across multiple hosts. Allowing B thus means that any version expression like "~X.X.X" or "^X.X.X" is dangerous and should not be used for Thrift. For me, the minimum scope of public API compat is 1 and B above. 2 and maybe 3 for Java only seems reasonable too. Concretely, largely quoting BCG, ## 1 * IDL file format * the CLI (compiler flags) * the common means of instantiating servers and clients in the various language libs (including setStringLengthLimit, setCertPath etc) * generated service interface * communication behaviors (on timeout, unknown handler exception etc) ## B * wire format ## 2 * generated struct methods * TMemoryBuffer methods (or Transport read/write in general ?) ## 3 * (the semantics of the read* and write* methods) On Wed, Jan 13, 2016 at 12:19 PM BCG <bgo...@hushmail.com> wrote: > On 01/12/2016 05:09 AM, Aki Sukegawa wrote: > > Speaking about versioning, semver mandates us a defined set of public API > > that is covered by it. > > As I don't think we can document every individual API, we need a set of > > rules that can decide what belongs to public API. > > For example, Protocol.readFieldEnd, is it public API ? > > > > > This seems like a shortcoming of "semver" for something like Thrift... > in my mind the concept of a public "API" for Thrift is multifaceted (are > we talking about the semantics of serializing/deserializing, the IDL > file format, the CLI for compiler, etc). I'm not saying that "semver" > is bad or anything just that it may not easily align with all projects. > > The situation is further complicated by the fact that each language lib > has its own "API"... so, for instance, some if change in the PHP lib > mandates rolling over the version number then that could have adverse > effects in other languages' package managers that base defaults off of > "semver" versioning (please correct me if I'm wrong about this... I'm > not too familiar with those tools I'm just basing my statement off of > what I've seen posted on this list). I'm not sure how to solve that... > seems like it might be difficult to make everyone happy in that regard. > > In any case, in my mind the "public API" should at least include the IDL > file format, the CLI, and the semantics of the read* and write* methods, > and the common means of instantiating servers and clients in the various > language libs. > > > >
