Standardize stability terms

[tigrannajaryan]

I wonder if we need to settle on some common terminology. We use different terms depending what we talk about, but I am not sure there are good reasons. In some place we use Experimental/Feature Freeze/Stable, some other places Alpha/Beta/Stable, somewhere else Unstable/Beta/Stable.

See https://github.com/open-telemetry/community/blob/main/maturity-matrix.yaml

Should we chose one set of names and stick to it? The meaning of each term can still have contextual nuances.

Related to #3456

[tigrannajaryan]

@open-telemetry/specs-approvers thoughts?

[reyang]

My personal opinion:

1. Use alpha/beta/rc/stable across all places (semantic conventions, API/SDK specs, packages, etc.).
2. Here are my suggestions regarding the semantics:
   • alpha - bleeding edge, normally for insiders to try out some idea, most people should keep away from it (e.g. maintainers are not encouraged to implement these unless explicitly communicated, users are not encouraged to use it).
   • beta - ready for broader preview/dogfooding users, with NO stability guarantee, features might be added/removed/redesigned.
   • rc (release candidate) - step towards stable, no plan to add new feature, certain feature might be removed, things might break although the bar is pretty high.
   • stable
   • deprecated - not encouraged, but still maintained/supported.
   • retired - dead end, don't expect support / security fix / etc.

[tigrannajaryan]

For visualization mapped to what we have now:

Proposed by @reyang	Current API Spec	Current Proto
Alpha	Experimental	Alpha
Beta	?	Beta *
RC	Feature Freeze	?
Stable	Stable	Stable
Deprecated	?	?
Retired	?	?

* we give additional guarantees, e.g. breaking changes no more than once per 3 months

[tigrannajaryan]

• beta - ready for broader preview/dogfooding users, with NO stability guarantee, features might be added/removed/redesigned.
• rc (release candidate) - step towards stable, no plan to add new feature, certain feature might be removed, things might break although the bar is pretty high.

The spec is currently formally missing these but we went through similar phases recently with Log Spec stabilization. We should formally capture what we are doing in reality.

[lmolkova]

Collector has similar stability levels, but adds a couple more statuses.

I believe the mapping for them should be:

Proposed by @reyang	Current API Spec	Current Proto	Collector
Alpha	Experimental	Alpha	Development
Beta	?	Beta *	Alpha
RC	Feature Freeze	?	Beta
Stable	Stable	Stable	Stable
Deprecated	?	?	Deprecated
Retired	?	?	?

There is also Unmaintained status which is similar to Retired, but can be given a new life if a new owner is found.

[dyladan]

Will this terminology also apply across the collector and SDKs? If so, we should see what terminology all SDKs are using as well.

[lmolkova]

Will this terminology also apply across the collector and SDKs? If so, we should see what terminology all SDKs are using as well.

We have "Project Status" section in many OTel SDK repo readmes and "Status and Releases" in template for opentelemetry.io docs.

They seem to be slightly inconsistent: e.g. otel-go already has Frozen status, otel-cpp uses Public release instead of stable(?) and otel-js has Development status.

It seems it'd be beneficial to unify them, but it should not conflict with language idiomatic ways to annotate artifacts (v0, -alpha, -rc, etc).

[update]: here're most of statuses used in SDK/contrib repos, separate from artifact stability annotations:

Proposal	API Spec	Proto	Collector	.NET/Java/C++/Python	Go	JS	Spec signal lifecycle	PHP	Swift	Rust
Development	-	-	Development	-	-	Development/Unreleased	-	-	in development	not yet implemented
Alpha	Experimental	Alpha	Alpha	Experimental	-	Experimental	Experimental	alpha	experimental	alpha
Beta	-	Beta *	Beta	-	Beta	Beta	-	beta	-	beta
RC	Feature Freeze	-	-	-	- **	-	-	-	-	-
Stable	Stable	Stable	Stable	Stable	Stable	Stable	Stable	-	Stable	-
Deprecated	-	-	Deprecated	-	-	Deprecated	Deprecated	-	-	-
Retired	-	-	Unmaintained	-	-	Unmaintained	Removed	-	-	-

** OTel Go SIG uses Frozen differently (no PRs accepted, regardless of the feature-work state)- #3459 (comment)

[tigrannajaryan]

@lmolkova did you intend to list Collector's Development in two rows? Can you please clarify? It seems if we only list it once and shift up Alpha and Beta we have more matches:

Proposal	Collector
Development	Development
Alpha	Alpha
Beta	Beta
RC	-
Stable	Stable
Deprecated	Deprecated
Retired	Unmaintained

[lmolkova]

@tigrannajaryan, good catch! fixed.

[tigrannajaryan]

@lmolkova Thanks! If you are interested there is an OTEP that proposes to align on the levels and terms: open-telemetry/oteps#232

[MrAlias]

The Go Frozen status does not mean RC, it means that development work is paused for the signal an no PRs will be accepted.

https://github.com/open-telemetry/opentelemetry-go#readme

[lmolkova]

I think release candidate and general Golang Frozen are quite similar

Sometimes a package reaches the end of its development cycle and is considered complete. It continues to be maintained, meaning regressions or breakages are fixed, but the scope becomes frozen and no new features are meant to be accepted.

in both cases it means no new features, just bug fixes

[MrAlias]

I think release candidate and general Golang Frozen are quite similar

The OTel Frozen status is not equivalent to Golang Frozen. Furthermore, it is not equivalent to RC, there is no candidate to consider for release. No development effort was ever spent on the signal.

[tigrannajaryan]

No development effort was ever spent on the signal.

If I understand correctly it is not a maturity level of a component per se. It is a signal in the repository which says "please don't submit PRs and create work for maintainers in this area for now". Seems like it is somewhat orthogonal concept, not strictly a maturity level.

[MrAlias]

No development effort was ever spent on the signal.

If I understand correctly it is not a maturity level of a component per se. It is a signal in the repository which says "please don't submit PRs and create work for maintainers in this area for now". Seems like it is somewhat orthogonal concept, not strictly a maturity level.

Correct 👍

[austinlparker]

Closed by open-telemetry/oteps#232

[tigrannajaryan]

We need to apply OTEP 0232 to this repo. I filed a new issue to track that work: #4051