Version numbers/semantic versioning

[aabmass]

I think there might be a bug here but also some discussion needed.

The current release versions {major}.{minor}b0 e.g. opentelemetry-api 0.13b0. However, after the release commit, the versions get updated for the next version with {major}.{minor}.dev0:

opentelemetry-python/opentelemetry-api/src/opentelemetry/version.py

Line 15 in 0e852ea

__version__ = "0.14.dev0"

It could totally be the case that this is a valid versioning scheme (could someone share some history on this), but seems like a bug in the release process to me. Do we want to use semver instead?

[lzchen]

Are you referring specifically to how {major}.{minor}b0 doesn't adhere to semvar because of the lack of a . after {minor}?

[aabmass]

Yes, and also the b0 should be after another hyphen for semver (see here). So like 0.14.0-b0 or similar. The patch should be a "numeric identifier"

Would be great to get some history on the current versioning scheme if anyone remembers how it came about

[lzchen]

I'm not really sure if there was any reasoning behind this, it looks like the discrepancy started from 0.1a.0 to 0.2a0. I am fine with changing the versions now if we have a good reason to.

From what you are saying, it appears the new template would be <major>.<minor>.<patch>-<pre-release>, with each of major, minor and patch, being a number. I'm wonder what the 0 after the b represents or do we only need the b to represent beta?

[aabmass]

From what you are saying, it appears the new template would be <major>.<minor>.<patch>-<pre-release>, with each of major, minor and patch, being a number

Yup I think that's right

I'm wonder what the 0 after the b represents or do we only need the b to represent beta?

We would only need b or beta. My understanding of semver is that the pre-release fields are intended to be pre-releases of a given version, e.g. 1.1.0-beta vs 1.1.0 (link):

A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

But I think if there is no "normal version" it still makes sense. Semver does say that all 0.y.z releases are for "initial development":

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

So presumably we don't need that suffix at all, and G.A. would be 1.0.0?

[lzchen]

But I think if there is no "normal version" it still makes sense. Semver does say that all 0.y.z releases are for "initial development":

Although this is true, if we deviate from what we are doing currently (removing beta and relying on the fact that the 0 represents initial development it may cause confusion (people might think it is not in beta anymore). As well, on nuget, they are using the beta flag. In OpenCensus we are using the 0 as the prefix but it is already in GA.

[aabmass]

@lzchen after doing a little more reading, here's my understanding:

• PyPA recommends using semantic versioning but only clauses 1-8

  • Python projects adopting semantic versioning should abide by clauses 1-8 of the Semantic Versioning 2.0.0 specification.

  • this specifically leaves out the clause 9 about "a pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version."
• Instead of -beta, PyPA recommends to do pre-release versioning like this with a dot e.g. .bN, .devN, etc. This is to comply with PEP440 which package managers (pip) use and doesn't allow the hyphen. More info here

So I suppose the recommendation is then {major}.{minor}.{patch}[.{devN | bN}] e.g. 0.13.0.b0. However, our current scheme, I believe, does comply with PEP440.

[lzchen]

Once we hit GA, we can adhere to semantic versioning (with patch numbers).