Publishing metrics as "alpha"

[breedx-splk]

It sounds like a decision was made to exclude the metrics modules from the BOM pre 1.0 (#2268) and to add an "alpha" qualifier to the metrics related artifact names (#2266). With the PR #2311 I attempted to inject "alpha" into the version string for the two metrics modules, but we discovered today that the snapshot artifacts don't contain alpha when they are published. I actually think that we probably want to roll that PR back and reopen the issue.

After hacking on this quite a bit today, we have kinda concluded that the nebula gradle plugin (which is used to automatically divinate a version number from the git repo tags) is basically incompatible with an approach that tries to publish different modules with different version strings. Nebula wants a top-level, singular version number. This makes sense, since the plugin is highly opinionated and since the version is driven from tags (tags apply across all submodules).

So, I'm opening this discussion to see how folks would like to try handling this. I came up with some ideas how how we might attack this challenge:

• Do some serious gradle hacking and force nebula and the publishing plugins to do what they aren't designed to do.
• Choose or build different tooling to manage the project/module versions (essentially ditching nebula)
• Fork the existing tooling and/or contribute back to upstream
• Reconsider the decision to add -alpha entirely. Unfortunately, people will have the wrong expectation when we hit v1.0.0 so this is dangerous at best (or probably mostly unviable).
• Reconsider using -alpha in the name of the module instead of the version string. This is straightforward and probably the easiest to implement, but there is push back because users will need to change their dependencies when metrics comes out of alpha. Apparently this was decided against in the recent past.
• Move metrics into their own project - that way it can be versioned independently from the rest of the project. Downsides are obviously dependency challenges and having to wrangle a separate project. This kinda also implies that that new project cannot use nebula if it is in the same repo.
• What else? Your ideas here!

Specifically curious what @anuraaga thinks, but maybe other folks like @iNikem and others think as well.

[breedx-splk]

Ok, this might also be a bit of a hack, but here's another stab at it #2329.

[iNikem]

I get it that the problem was solved? :)

[jkwatson]

Yes, the latest PR got this working. 🎉

[jonatan-ivanov]

I think this discussion is connected to the topic we had on the Metric Workshop. According to @tedsuo, the OTel artifacts that aren't reached their stable state are published with a 0.x version numbering scheme. This does not seem to be the case for opentelemetry-java which seems to be published as 1.0.0-alpha while it is still unstable.

Using a 1.0 numbered version with an alpha release has a mixed message - usually pre-GA/non-stable releases are numbered less than 1.

Timing of the metrics alpha release currently seems coupled with the 1.0 GA/stable release of other components - since none of the GA/stable components depend on metrics, the release coupling is unnecessary and could be a source of confusion to users.

Can this be fixed for opentelemetry-java so that it will be consistent to others components and less confusing for users?

/cc @bogdandrutu @jmacd @shakuzen

[jkwatson]

@jonatan-ivanov The Java SIG has decided that this is the pattern we will be using, and it is in line with semver. We're going to try to keep all the artifacts with the same base version, as much as we possibly can.

There is no hard requirement that all languages use precisely the same versioning scheme, and we think it will be less confusing for users this way.

[jkwatson]

To add on to this, I believe our plan is to continue with a (probably monthly) regular release cycle of minor version updates, even post 1.0. It totally makes sense to release a new version each month that will include breaking changes to the pre-release signals.

And, Anuraag is absolutely correct. If you're using pre-stable artifacts, you're going to be in for a lot more pain than just some very minor confusion about having a -alpha label on the version numbers. Things are going to be breaking for you at pretty much every release until we're ready to merge those signals into the main artifacts and leave the -alpha artifacts behind.

[jkwatson]

Just as one further comment, speaking as a maintainer.

Yes, some of this is quite maintainer-centric. But, if we have to change our build/deploy/release system in order to accommodate a new versioning scheme (which will only potentially positively impact users of unstable signals), it will even further delay our releasing a 1.0 version of this library. We are getting enormous pressure at the moment to release a stable version. Is it worth delaying that release for another month to make changes? Changes that will only be of temporary impact until we've got the other signals stabilized?

[shakuzen]

I think we also may need to provide an alpha-bom, we left alpha out of BOM since we wanted users to know what they're getting into by specifying the alpha version explicitly.

My comment was in the context of post-GA for metrics - it wouldn't matter if metrics had a different version because users would be expected to use the BOM to avoid needing to specify individual versions. The alpha version not being included in the BOM sounds like a good idea to me. Users should be very aware they are using a non-GA version and non-GA versions not being part of the BOM sounds standard.

To clarify a bit my original comment, whether metrics is in another repo or not is not as important (though I think it helps make more clear its status as not part of the GA) as whether it can be released separately until at least it goes GA. The idea being that frequency and type of changes (patch vs minor) in one area didn't affect another. If you're planning to do frequent minor releases anyways, maybe it's a moot point. I suppose I was envisioning release cadence post-GA for minor versions more in line with other popular open source Java projects.

I think the message is a bit mixed when it's said that alpha versions shouldn't be used by end users but they're released with everything else that users should use, from the start of GA. I understand the -alpha version should be enough indication, but perhaps I'm weary from past mistakes like all the libraries that added dependencies on non-GA OpenTracing dependencies even though those were 0.x versions. This time it will be 1.x versions with an -alpha qualifier. Will the message that alpha versions aren't for end users be received and understood widely? That's my concern.

[anuraaga]

I'm weary from past mistakes like all the libraries that added dependencies on non-GA OpenTracing dependencies even though those were 0.x versions. This time it will be 1.x versions with an -alpha qualifier.

This makes me think even more that the current versioning scheme sounds ok, as even with 0.x people may just use it even though they shouldn't. I agree the messaging isn't so clear though on whether the unreleased signals should be strongly avoided by end users or not. I'm hoping so @tedsuo.

As for discourating their use even more, I'd be fine with adding a log message on classload to each artifact, or at least the primary one, metrics entry point, saying they are using unsupported code and should reconsider. Java agent can just rewrite the log message away :) @jkwatson what do you think?

[jkwatson]

As for discourating their use even more, I'd be fine with adding a log message on classload to each artifact, or at least the primary one, metrics entry point, saying they are using unsupported code and should reconsider. Java agent can just rewrite the log message away :) @jkwatson what do you think?

I wouldn't fight it, but it seems like a bit of overkill to me. We should just make it clear (and I think we've made it clear in the past few months) that if you use unstable libraries (which we now tag with -alpha on their versions), you are going to be dealing with frequent breaking changes.

[jkwatson]

FYI, please comment on open-telemetry/opentelemetry-specification#1291. In that PR, it is called out that versioning signals independently is the exception only for languages with package managers that do not support unstable versions above 1.0.