Decide on a naming scheme for "important" iterations on the OpenTracing specification

[bhs]

This has come up a few times, most recently here. Using semver for the OpenTracing spec itself would be excessively confusing... there would be (a) the semver for the OT spec, (b) the semver for the particular OT language API, and (c) the semver for the tracing implementation. Too many numbers!

I would rather come up with an ordered naming scheme for "important" (*) OpenTracing specification iterations... maybe alphabetical nouns in a given category. (C.f. Ubuntu's naming scheme or whatever)

(*): Not sure what "important" means... doesn't just have to be "breaking" changes to the spec.

[wu-sheng]

@yurishkuro @cwe1ss
continue to discuss.

As @cwe1ss said, using the same version maybe not a good idea. But as a spec, OT can use a single number( not include dot in version number), like OT v1, OT v2, etc. OT spec won't have a bug or a reflection needs

Fot the particular OT language API, they use their self define version num, or traditional version num, only to use the first version num as same as OT spec. such as: OpenTracing-java impl can use 1.x.x as a version number, which declares to support OT v1 spec.

This is very easy to understand for all users. This type of version naming is something like JDK spec.

And for (c) the semver for the tracing implementation, it can wait, let every team to decide. Any team's homepage will show the relation between tracing implementation's version and OT version.

[bhs]

We could also do roman numerals for the OT spec version... OpenTracing I, OpenTracing II, etc?

[wu-sheng]

Roman num is very clear when it's less than 12. like Ⅰ Ⅱ Ⅲ ... Ⅹ ... Ⅻ. May be it's good enough for now?

Too large num may be not so pretty?

[bhs]

I think the "Roman Numerals" idea is the first one I've actually felt excited about for more than 24 hours. @yurishkuro what do you think?

[yurishkuro]

I suppose I am not so worried about the exact naming/numbering as about what we intend to use it for. For example, how do the following changes affect the versioning?

• correcting a typo
• rephrasing a sentence
• fixing incorrect sentence
• adding new standard tag/field
• changing semantic restrictions (e.g. something about baggage encoding or propagation)
• changing conceptual API (e.g. the change when we moved get/set baggage from Context to Span)

When a tracer implementation says it is compatible with OT #X, and we do one of the above, does it still remain compatible with X, or do we need to bump X somehow?

It feels to me that without clear definition of the versioning deciding on representation of the versioning is rather pointless.

Having said that, I still prefer semver for the spec, because it kind of deals with all these questions already.

[bhs]

@yurishkuro I was imagining that OT #(N) becomes OT #(N+1) when some new "important" feature(set) is added, or certainly when something substantial is removed. Additions to standard tags would not affect the OT version in this scheme.

If tracer impls want to talk about compatibility, I would assume they would refer to their per-language OT API (as a semver). For me the versioning is more about setting project milestones than anything else.

[yurishkuro]

I ran a quick poll on the team:

• "OpenTracing I" - 1 vote
• "OpenTracing 1.0" - 4 votes (with understanding that "1.0" is not a semver, but a literal name)

[wu-sheng]

@bensigelman , @bensigelman , whatever the type of version num be chosen, the version num of the spec should be very precise. Any version, be released, should NOT be changed in any way, including Additions to standard tags, etc. If have any changed, it will make confused to followers.

The OpenTracing 1.0 is more common to developers. Maybe @bensigelman think "Roman Numerals" is more cooler.

[wu-sheng]

I think the type of version num should be confirmed as soon as possible. And all new spec can follow it.

[bhs]

@wu-sheng

Any version, be released, should NOT be changed in any way, including Additions to standard tags, etc. If have any changed, it will make confused to followers.

If we went with ^^^, we would also need to do semver for the OT spec. Otherwise we'll end up with "OpenTracing v4257.0" which is not useful :)

@yurishkuro re your straw poll: thanks for the info. I am still mulling over what I think about having semver for OpenTracing proper vs having semver for per-language OpenTracing repos. We clearly need the latter. Given that, it's not at all obvious to me that having a second semver for the former is adding value (rather than adding confusion).

Perhaps I should get back on the task of creating a monthly VC/hangout meeting schedule for committers, as this is just the sort of thing I don't like resolving over Github Issues :)

[cwe1ss]

I don't have experience with specifications but roman numerals seem a bit strange to me. I'd prefer regular numbers as well.

Since there's just the website and no formal versioned specification document, I'm wondering if we even need the patch version part? I think the specification could use "1.1", "1.2", "2.0" with the following rules:

• minor changes that don't change the meaning (typos, rephrasing, more explanations) don't change the version number.
• non-breaking additions increase the minor version
• breaking changes increase the major version

I don't think there's a good/realistic way to keep the specification, all implementations, contrib packages and tracers in sync.

I think it's more important that every package follows SemVer rules to make sure people don't see surprises when they update packages. However, maybe we should reference the targeted specification version in the package descriptions?!

I guess the main reason for a version mismatch will be an outdated package (e.g. implementation already targets 2.0 but tracer still targets 1.0). As long as we keep all packages current, everybody should be able to target the most recent version of the specification.

So preventing version mismatches between the several parts might be an organizational issue for us.

[wu-sheng]

• minor changes that don't change the meaning (typos, rephrasing, more explanations) don't change the version number.
• non-breaking additions increase the minor version
• breaking changes increase the major version

@bensigelman , my meaning for Any version, be released, should NOT be changed in any way, is as same as @cwe1ss. major.minor version style, I think it's enough for any spec, from all specs I have known.

Maybe this time, we come to an agreement only on the version of the spec.

• Implements ,only including: opentracing-java, opentracing-python, etc. , maybe can only match the major version in their SemVer.
• Leave all other implements, including contrib packages, tracers , etc. , in their SemVer as usual. They can describe the target version of spec as they like.

Further more, if we decide to use any spec version, we need to keep all version spec in a release list. Some people will need to read old version spec for following reason:

• Implements target to different version of spec will become inevitable, sync all implements is a impossible mission.

[wu-sheng]

@bensigelman , if you want a have a chat with all committers on google hangouts, you may can find me from wu.sheng.841108@gmail.com. Now, I can only use google service on mac, these is a firewall block for google in China. I have never used hangouts yet, not sure it's working.

If there is any problem, please let me known on github. Thank you for your understanding.

[bhs]

The point of the roman numeral thing is to make sure people realize that it's not semver... i.e., it is "intentionally weird" :)

But I can tell that nobody else likes this idea very much! So I think @cwe1ss's proposal is a sane way to at least avoid having a patch version for the spec.

I am also thinking that this will be easier now that there's a github.com/opentracing/specification repository proper. I would like to create a spec.md file therein which is more formal than the current prose document on opentracing.io... It'll be an easier thing to link to, and we can put git tags on the repo to match the Major.Minor versions.

[yurishkuro]

@bensigelman agreed about spec.md. Right now we're discussing the versioning of a vaguely artifact.

[wu-sheng]

@bensigelman , spec.md should link to different version of OT spec. Also maybe choose version from opentracing.io online doc.

Major.Minor version rule should follow:

• Major Version: Big change to the spec, OT API. Such as, change the Data Conventions, moving the set baggage item from SpanContext to Span
• Minor Version: Addition mini features to the spec. Such as, add a tag to HTTP Server Tag.

And @bensigelman , @yurishkuro , no matter what versioning rules are, should we to set the current version to 1.0? I used 1.0 in my translation-version, hoping it's as same as OT spec version.

[bhs]

(See #20)

[bhs]

opentracing/opentracing.io#178 brings things forward a bit.