expose OpenTracing and API versioning capabilities

[bhs]

Per opentracing/opentracing.io#33 and opentracing/opentracing-go#51 (comment)

@bcronin @yurishkuro

[bhs]

(I delinted and found some spaces/tabs things... probably my copy of vim)

[bhs]

@bcronin how about this latest version?

[bcronin]

The update addresses the "two copies" scenario I was concerned with, so now I'm descending to the next level of detail at this point (i.e. naming)...

I can't help but think it'd be a lot more straightforward to just have:

def version():
    return '0.9.0'

• TL;DR: It's simpler :)
• As a blanket generalization, I'd argue making it a simple method translates to a more uniform interface across languages (e.g. I'm thinking of C++ and Go)
• In reality, I'd argue fairly strongly it is not a burden to implementors to have to implement this method! :) Worrying about an abstract base class just to avoid implementors having to implement a method returning a fixed string, IMHO, adds abstraction complexity and no actual, real-world value. Also, I'd argue, OpenTracing API versions shouldn't be changing that often that keeping this value up to date should be any maintenance burden (note: this claim does not apply to the implementation version which in theory changes with every push by the implementator)
• OPENTRACING_PYTHON_API_SEMVER seems awkwardly verbose: the OPENTRACING and PYTHON part should be self-evident. I think that it's a semantic version is a documentation point (and I tend thinking using straightforward, full words is better than abbreviations when it's possible - i.e. version).
• I also think including "API" in the name is unnecessary given the presence of something called implementation_id (this is harder to objectively argue, but I prefer the short name and would be surprised if consumers of OpenTracing found version confusing). That said, I believe I would still find a way to sleep soundly at night if it was called api_version :)

All in all, I think Tracer.version() would be simpler but I realize it's a large part just opinion and am not overly concerned about this.

[bhs]

Having slept on this, the only thing I really want to expose at this point is the semver of the per-platform OpenTracing API. I don't want the OT implementor to have to remember to update same, hence the use of the constant rather than a method which should be overridden.

Note that the per-platform semvers will not be in lock-step across the various platforms (if we refactor the API in one language, its semver will need to change, but there's no reason that the others must follow suit). Someday it would be nice to semver the platform-indepedent OpenTracing specification, but for now it's not formal enough to make a semver meaningful (in my opinion, anyway).

Thoughts?

In the meantime, I will trash the impl-id stuff entirely.

[bhs]

(trashing complete!)

[bcronin]

Ah, ok - the intent is to expose the platform API version which may be independent of the spec version. That still allows for "two copies" case to be handled, so I'm fine with this.

[yurishkuro]

Github confused me with the ordering of the comments...

1. I prefer a method to a class constant
2. I don't like that method to be returning a version string. It reminds me of that horrible user-agent parsing that JavaScript used to do to determine browser capabilities.

[bhs]

@yurishkuro

1. The class constant was supposed to make it harder for an implementor to imagine that they're supposed to override in their subclass. Kind of like declaring a method final in Java (or something), but with static content. No super-strong feelings about that, though, and the lack of a docstring is annoying with the constant.
2. Are you suggesting a version tuple (of ints), or are you suggesting a struct-like thing with only a single version field for now? Or something else?

[yurishkuro]

@bensigelman

1. Not sure I understand the scenario. If tracer lib imports v.0.8 of opentracing API and extends the Tracer, it inherits the method with the correct version. Are we saying that the end user app has v.0.9 opentracing lib, but tracer impl written against 0.8? If that's the case, we can make the method abstract in the opentracing tracer, but that's not going to protect against implementor forgetting to bump the version. And I would also think the tracer's dependency should be <0.9 in this case.
2. I meant that exposing capabilities via version seems like a very fragile method. I can't imagine how ugly the client code will look doing those checks. The usual approach to combat API version changes is to forward or backport the API via a shim. E.g. if the instrumentation is done via v.0.9 but the bound tracer is only v.0.8 than the tracer should be wrapped in a decorator..

But I have to admit that I haven't had the pleasure of writing such spaghetti code in dynamic langauges and checking versions, so I don't want to -1 this if people feel strongly that it's needed.

[bhs]

@yurishkuro

1. I'm just saying that this particular version number is a property of the API, not of the implementation. So there's no need for the impl to override it, and thus no need to make it a method in an interface where all of the other methods are meant to be overridden.
2. A capabilities API would be more robust but also easier to regret / need to remove. I was trying to think of the smallest version-related change (i.e., something to address Add API to query OpenTracing version at runtime opentracing.io#33) that we would probably not want to remove in the future.

Thoughts? I am not attached to this PR but wanted to take a stab at opentracing/opentracing.io#33 without adding a ton of complexity.

[yurishkuro]

1. It's a question of the use case. If an app manages to load conflicting versions of OT API lib and tracer implementation, and tracer simply refers to a constant in the API, then it's not representing what it actually implemented. The scenario is hard to imagine in java/go, unusual in Python under normal pip-based dependency management, and I have no idea about JS.
2. Fair enough. If (1) changes your mind to use a method, I'd call it api_version, not just version.

[bhs]

JS is a free-for-all... @bcronin actually understands it (I do not; or not well). I'll sleep on this whole thing... part of me wants to back it out until we have an actual specific problem to solve in the wild.

[bcronin]

The spirit of #33 was to provide a simple means of accessing the version of the OpenTracing standard being implemented against. If there also needs to be a separate notion of a platform version that can vary independently, frankly I think that adds additional complexity counter to the original goal and I suspect the intended value gets lost.

I think there's some (bear with a bit of soapboxing here to make myself feel better) danger in waiting until there's an actual specific problem to solve in the wild as that sort is missing a large part of adding versioning from the start. (Also, for the record most of my forward/backwards compatibility experience here has to do with drivers and plug-ins in C++ SDK architectures, not JavaScript, but the API scope here is much smaller so I'm totally willing to concede that I may be overthinking it.)

Anyway, my soapboxing done and stepping back, there are things I'd rather prioritize here and, in practice, even if it's not elegant, people almost always find some way to work around version incompatibilities, so I think it'd be net-best to close #33.

[bhs]

(withdrawing per the fate of opentracing/opentracing.io#33)