From 78de57809d289efee9f8fcc74df3fd3bcbd0507a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Fri, 9 Jun 2023 14:24:26 -0300 Subject: [PATCH 01/17] Framework for defining the maturity of OpenTelemetry and its SIGs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0000-maturity-of-otel.md | 149 ++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 text/0000-maturity-of-otel.md diff --git a/text/0000-maturity-of-otel.md b/text/0000-maturity-of-otel.md new file mode 100644 index 000000000..6d2a773fe --- /dev/null +++ b/text/0000-maturity-of-otel.md @@ -0,0 +1,149 @@ +# Framework for defining the maturity of OpenTelemetry and its SIGs + +On 08 Mar 2023, the OpenTelemetry GC and TC held an OpenTelemetry Leadership summit, discussing various topics. One of the themes we discussed was establishing standard rules for describing the maturity of the OpenTelemetry project. This OTEP summarizes what was discussed there and is intended to have the wider community provide feedback. + +This OTEP builds on what was previously communicated by the project, especially on the following page: https://opentelemetry.io/docs/reference/specification/versioning-and-stability. + +The Collector’s [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels) inspired the maturity levels. + +## Motivation + +Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the project's maturity. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users. + +Only once we reach the “stable” level at the project level will we be ready to consider graduating OpenTelemetry at the CNCF, with all of the Tier-1 SIGs being in the context of the graduation, including their Tier-1 Components. This OTEP provides a framework for describing project maturity as a whole. + +## Glossary + +* *SIG:* an official SIG within the OpenTelemetry project, like the Collector or Java. Some WGs are temporarily accepted, given they should be SIGs instead of WGs, like the Semantic Conventions WG. +* *Tier-1 SIG:* a SIG within the OpenTelemetry project deemed critical by the GC/TC. +* *Candidate Tier-1 SIG:* a SIG that is deemed as critical for the future of the project, but might not be of the same maturity level yet. It’s expected to reach that level eventually, and other Tier-1 SIGs should be prepared to accommodate the new component as needed. +* *Component:* module maintained by a SIG like a Collector exporter or an SDK sampler. +* *Tier-1 Component:* a component selected by project maintainers as critical for the SIG. For instance, the OTLP receiver will likely be selected as a Tier-1 Component of the Collector. See Tier-1 Components for more details. +* *Candidate Tier-1 Component:* similar to “Candidate Tier-1 SIG”, but for a component within a SIG. +* *Dependency:* an OpenTelemetry SIG or component that is required by another SIG or component. For instance, the OTLP Logs Data Model from the Spec is required for the Collector’s Logging support. + +## Explanation + +### Maturity levels + +SIGs and components of a project MUST have a declared maturity level established by SIG maintainers (SIGs). The maturity level for a SIG or component is, at most, the lowest level of its dependencies or priority components. For instance, if the Collector SIG maintainers declare the “otlpreceiver” component as a tier-1 component of the Collector core distribution, and the “otlpreceiver” declares a dependency on the OpenTelemetry Collector API “config” package which is marked with a maturity level of “beta”, the “otlpreceiver” can be at most “beta”. The OpenTelemetry Collector “core” distribution is also affected so that it can be at most “beta”. + +Only once all dependencies are marked as “stable” MAY a component be marked as “stable”. Only once all Tier-1 Components of a SIG are “stable” MAY that SIG be marked as “stable”. + +#### Development + +Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, ...). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. + +#### Alpha + +This is the default level: any components with no explicit maturity level should be assumed to be “Alpha”. The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The configuration options might often change without backward compatibility guarantees. + +#### Beta + +Same as Alpha, but the interfaces (API, configuration, generated telemetry) are treated as stable whenever possible. While there might be breaking changes between releases, component owners should try to minimize them. A component at this stage is expected to have had exposure to non-critical production workloads already during its Alpha phase, making it suitable for broader usage. + +#### Stable + +The component is ready for general availability. Bugs and performance problems should be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are not expected to happen without prior notice unless under special circumstances. + +#### Deprecated + +Development of this component is halted, and no further support will be provided. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed. + +#### Unmaintained + +A component identified as unmaintained does not have an active code owner. Such components may have never been assigned a code owner, or a previously active code owner has not responded to requests for feedback within 6 weeks of being contacted. Issues and pull requests for unmaintained components SHOULD be labeled as such. After 6 months of being unmaintained, these components MAY be deprecated. Unmaintained components are actively seeking contributors to become code owners. + +### Specification requirements + +The specification should declare all requirements for a specified component to be declared stable. When implementations are still missing features required by the specification, they can be at most Alpha status. + +### Tier-1 SIGs + +This OTEP recommends the following SIGs to be included as part of the Tier-1 SIGs for OpenTelemetry: + +* Spec General +* Semantic Conventions (WG) +* Java +* Java auto-instrumentation +* Go +* .Net +* JavaScript + +Once this OTEP is approved, the TC and GC members will vote on the individual SIGs from the list above and are free to make further suggestions. A final list of Tier-1 SIGs shall be in the “community” repository. + +### Tier-1 Components + +When discussing the components' maturity, we often debate what should be included in the evaluation criteria. To help clarify that, we introduce the concept of “Tier-1 SIGs” and “Tier-1 Components”. Tier-1 Components are critical for a specific SIG: only when all Tier-1 Components are stable can a project be evaluated as stable. For instance, the “OTLP receiver” for the OpenTelemetry Collector could potentially be a “Tier-1 Component”. Only after this component is declared stable may the Collector be declared stable, provided all other Tier-1 Components are also stable. + +Projects MUST list their Tier-1 Components in the main readme file. A Tier-1 Component MAY be hosted under the project’s “contrib” repository. Not all components under the main repository (sometimes called the “core” repository) are automatically Tier-1 Components. + +A component can be declared “Tier-1” only if they have the following characteristics: +* The component has at least the same maturity level as the SIG +* The component has a clear code owner +* The code owner is active within the project +* The maintainers of the project are comfortable supporting the component should the code owner decide to step down or leave the project + +### Tier-1 Signals + +Similar to a Tier-1 Component, a Tier-1 Signal must have stable support in order to declare OpenTelemetry as stable. Declaring a signal as Tier-1 means that all projects must also see that signal as required for declaring the project stable. + +Not all signals will have the same requirements. For instance, Logs might not provide an instrumentation API specification. + +List of Tier-1 signals and their capabilities: +* Logs + * Data model + * SDK specification + * Instrumentation SDKs + * Bridge API specification +* Metrics + * Data model + * API specification + * Instrumentation APIs + * SDK specification + * Instrumentation SDKs +* Traces + * Data model + * API specification + * Instrumentation APIs + * SDK specification + * Instrumentation SDKs + +The lifecycle of a signal is defined in the following document: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/ . While the stability and versioning of the signals may relate to this OTEP, the previously linked document specifies the details on how to reach the “stable” level mentioned in this OTEP. + +The “experimental” level from the signal versioning and stability document relates to the “alpha” and “beta” levels from this OTEP, “stable” and “deprecated” are equivalent to their counterparts on this document, and “removed” is non-existent here. + +When a new signal reaches the “stable” level, OpenTelemetry TC and GC will ultimately decide whether to include it as part of OpenTelemetry’s priority components, using the process described in [Promoting SIGs and components](#promoting-sigs-and-components). + +### Promoting SIGs and components + +SIGs can request to be included in the Tier-1 List by contacting a TC or GC member. The TC/GC member will bring the request to the TC/GC via Slack or Zoom call, who will vote on the matter. A simple majority suffices for including the SIG. The SIG needs to have at least equal maturity as the project. For instance, if OpenTelemetry’s maturity is set to Beta, the coming SIG has to be at least Beta as well, so that it doesn’t downgrade the main project’s maturity. + +Components can request project maintainers to be included in the Tier-1 list via a GitHub issue created on the main repository of the SIG. The SIG maintainers will then vote on the matter. A simple majority suffices for including the component. The component needs to have at least equal maturity as the SIG so that it doesn’t downgrade the SIG’s maturity. If SIG maintainers have strong reasons to include a component with a lower status, they can request an exception with the GC/TC. A supermajority vote is required to accept the request until the project reaches the “Stable” level so the project’s scope doesn’t continuously grow. After we reach the “Stable” level, a simple majority decision will be sufficient. + +SIGs or components that are seen by the maintainers as critical for the future of the project, like a new signal, are added to the Candidate Tier-1 List. Once this happens, the other Tier-1 SIGs or components need to evaluate whether they need to be changed to accommodate the new candidate. + +### Downgrading SIGs and components + +While we don’t expect SIGs and components to be downgraded, there may be situations where the evolution of the project or SIG is affected by the inaction of specific SIGs or components. For instance, if a new signal is added to the Candidate Tier-1 List and a SIG fails to adopt this new signal within a reasonable time, the GC/TC may choose to remove the SIG from the project’s Tier-1 List. To do that, two TC/GC members must sponsor the removal proposal, and a supermajority vote (two-thirds) is required to accept the proposal. + +Similarly, if a component becomes unmaintained or isn’t of interest to the SIG maintainers anymore, it can be removed from the Tier-1 List. A simple majority vote by the SIG maintainers is required to accept the proposal. + +## Trade-offs and mitigations + +This approach gives both a top-down and a bottom-up approaches, allowing the GC/TC to determine what are the Tier-1 SIGs for OpenTelemetry as a whole, while still allowing SIG maintainers to determine what's in scope within their areas of expertise. + +## Prior art and alternatives + +* The specification status has a ["Component Lifecycle"](https://opentelemetry.io/docs/specs/status/) description, with definitions that might overlap with some of the levels listed in this OTEP. +* The same page lists the status of the different parts of the spec +* The ["Versioning and stability for OpenTelemetry clients"](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#signal-lifecycle) page has a detailed view on the lifecycle of a signal and which general stability guarantees should be expected by OpenTelemetry clients. Notably, it lacks information about maturity of the Collector. This OTEP could be seen as clashing with the last section of that page, "OpenTelemetry GA". But while that page established a point where both OpenTracing and OpenCensus would be considered deprecated, this OTEP here defines the criteria for calling OpenTelemetry "stable" and making that a requirement for a future graduation. This would also make it clear to end-users which parts of the project they can rely on. +* The OpenTelemetry Collector has its own [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels), which served as inspiration to the ones here. + +## Open questions + +None at the moment. + +## Future possibilities + +This change clears the path for a future graduation, by providing an objective way to evaluate what should be included in the graduation scope. \ No newline at end of file From 602532f5a3f53c839031e731e4347923d9921727 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Fri, 9 Jun 2023 14:54:16 -0300 Subject: [PATCH 02/17] Unified quotes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- ...ty-of-otel.md => 0232-maturity-of-otel.md} | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) rename text/{0000-maturity-of-otel.md => 0232-maturity-of-otel.md} (67%) diff --git a/text/0000-maturity-of-otel.md b/text/0232-maturity-of-otel.md similarity index 67% rename from text/0000-maturity-of-otel.md rename to text/0232-maturity-of-otel.md index 6d2a773fe..8c4b708c6 100644 --- a/text/0000-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -4,31 +4,31 @@ On 08 Mar 2023, the OpenTelemetry GC and TC held an OpenTelemetry Leadership sum This OTEP builds on what was previously communicated by the project, especially on the following page: https://opentelemetry.io/docs/reference/specification/versioning-and-stability. -The Collector’s [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels) inspired the maturity levels. +The Collector's [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels) inspired the maturity levels. ## Motivation Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the project's maturity. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users. -Only once we reach the “stable” level at the project level will we be ready to consider graduating OpenTelemetry at the CNCF, with all of the Tier-1 SIGs being in the context of the graduation, including their Tier-1 Components. This OTEP provides a framework for describing project maturity as a whole. +Only once we reach the "stable" level at the project level will we be ready to consider graduating OpenTelemetry at the CNCF, with all of the Tier-1 SIGs being in the context of the graduation, including their Tier-1 Components. This OTEP provides a framework for describing project maturity as a whole. ## Glossary * *SIG:* an official SIG within the OpenTelemetry project, like the Collector or Java. Some WGs are temporarily accepted, given they should be SIGs instead of WGs, like the Semantic Conventions WG. * *Tier-1 SIG:* a SIG within the OpenTelemetry project deemed critical by the GC/TC. -* *Candidate Tier-1 SIG:* a SIG that is deemed as critical for the future of the project, but might not be of the same maturity level yet. It’s expected to reach that level eventually, and other Tier-1 SIGs should be prepared to accommodate the new component as needed. +* *Candidate Tier-1 SIG:* a SIG that is deemed as critical for the future of the project, but might not be of the same maturity level yet. It's expected to reach that level eventually, and other Tier-1 SIGs should be prepared to accommodate the new component as needed. * *Component:* module maintained by a SIG like a Collector exporter or an SDK sampler. * *Tier-1 Component:* a component selected by project maintainers as critical for the SIG. For instance, the OTLP receiver will likely be selected as a Tier-1 Component of the Collector. See Tier-1 Components for more details. -* *Candidate Tier-1 Component:* similar to “Candidate Tier-1 SIG”, but for a component within a SIG. -* *Dependency:* an OpenTelemetry SIG or component that is required by another SIG or component. For instance, the OTLP Logs Data Model from the Spec is required for the Collector’s Logging support. +* *Candidate Tier-1 Component:* similar to "Candidate Tier-1 SIG", but for a component within a SIG. +* *Dependency:* an OpenTelemetry SIG or component that is required by another SIG or component. For instance, the OTLP Logs Data Model from the Spec is required for the Collector's Logging support. ## Explanation ### Maturity levels -SIGs and components of a project MUST have a declared maturity level established by SIG maintainers (SIGs). The maturity level for a SIG or component is, at most, the lowest level of its dependencies or priority components. For instance, if the Collector SIG maintainers declare the “otlpreceiver” component as a tier-1 component of the Collector core distribution, and the “otlpreceiver” declares a dependency on the OpenTelemetry Collector API “config” package which is marked with a maturity level of “beta”, the “otlpreceiver” can be at most “beta”. The OpenTelemetry Collector “core” distribution is also affected so that it can be at most “beta”. +SIGs and components of a project MUST have a declared maturity level established by SIG maintainers (SIGs). The maturity level for a SIG or component is, at most, the lowest level of its dependencies or priority components. For instance, if the Collector SIG maintainers declare the "otlpreceiver" component as a tier-1 component of the Collector core distribution, and the "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" can be at most "beta". The OpenTelemetry Collector "core" distribution is also affected so that it can be at most "beta". -Only once all dependencies are marked as “stable” MAY a component be marked as “stable”. Only once all Tier-1 Components of a SIG are “stable” MAY that SIG be marked as “stable”. +Only once all dependencies are marked as "stable" MAY a component be marked as "stable". Only once all Tier-1 Components of a SIG are "stable" MAY that SIG be marked as "stable". #### Development @@ -36,7 +36,7 @@ Not all pieces of the component are in place yet, and it might not be available #### Alpha -This is the default level: any components with no explicit maturity level should be assumed to be “Alpha”. The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The configuration options might often change without backward compatibility guarantees. +This is the default level: any components with no explicit maturity level should be assumed to be "Alpha". The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The configuration options might often change without backward compatibility guarantees. #### Beta @@ -70,15 +70,15 @@ This OTEP recommends the following SIGs to be included as part of the Tier-1 SIG * .Net * JavaScript -Once this OTEP is approved, the TC and GC members will vote on the individual SIGs from the list above and are free to make further suggestions. A final list of Tier-1 SIGs shall be in the “community” repository. +Once this OTEP is approved, the TC and GC members will vote on the individual SIGs from the list above and are free to make further suggestions. A final list of Tier-1 SIGs shall be in the "community" repository. ### Tier-1 Components -When discussing the components' maturity, we often debate what should be included in the evaluation criteria. To help clarify that, we introduce the concept of “Tier-1 SIGs” and “Tier-1 Components”. Tier-1 Components are critical for a specific SIG: only when all Tier-1 Components are stable can a project be evaluated as stable. For instance, the “OTLP receiver” for the OpenTelemetry Collector could potentially be a “Tier-1 Component”. Only after this component is declared stable may the Collector be declared stable, provided all other Tier-1 Components are also stable. +When discussing the components' maturity, we often debate what should be included in the evaluation criteria. To help clarify that, we introduce the concept of "Tier-1 SIGs" and "Tier-1 Components". Tier-1 Components are critical for a specific SIG: only when all Tier-1 Components are stable can a project be evaluated as stable. For instance, the "OTLP receiver" for the OpenTelemetry Collector could potentially be a "Tier-1 Component". Only after this component is declared stable may the Collector be declared stable, provided all other Tier-1 Components are also stable. -Projects MUST list their Tier-1 Components in the main readme file. A Tier-1 Component MAY be hosted under the project’s “contrib” repository. Not all components under the main repository (sometimes called the “core” repository) are automatically Tier-1 Components. +Projects MUST list their Tier-1 Components in the main readme file. A Tier-1 Component MAY be hosted under the project's "contrib" repository. Not all components under the main repository (sometimes called the "core" repository) are automatically Tier-1 Components. -A component can be declared “Tier-1” only if they have the following characteristics: +A component can be declared "Tier-1" only if they have the following characteristics: * The component has at least the same maturity level as the SIG * The component has a clear code owner * The code owner is active within the project @@ -109,25 +109,25 @@ List of Tier-1 signals and their capabilities: * SDK specification * Instrumentation SDKs -The lifecycle of a signal is defined in the following document: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/ . While the stability and versioning of the signals may relate to this OTEP, the previously linked document specifies the details on how to reach the “stable” level mentioned in this OTEP. +The lifecycle of a signal is defined in the following document: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/ . While the stability and versioning of the signals may relate to this OTEP, the previously linked document specifies the details on how to reach the "stable" level mentioned in this OTEP. -The “experimental” level from the signal versioning and stability document relates to the “alpha” and “beta” levels from this OTEP, “stable” and “deprecated” are equivalent to their counterparts on this document, and “removed” is non-existent here. +The "experimental" level from the signal versioning and stability document relates to the "alpha" and "beta" levels from this OTEP, "stable" and "deprecated" are equivalent to their counterparts on this document, and "removed" is non-existent here. -When a new signal reaches the “stable” level, OpenTelemetry TC and GC will ultimately decide whether to include it as part of OpenTelemetry’s priority components, using the process described in [Promoting SIGs and components](#promoting-sigs-and-components). +When a new signal reaches the "stable" level, OpenTelemetry TC and GC will ultimately decide whether to include it as part of OpenTelemetry's priority components, using the process described in [Promoting SIGs and components](#promoting-sigs-and-components). ### Promoting SIGs and components -SIGs can request to be included in the Tier-1 List by contacting a TC or GC member. The TC/GC member will bring the request to the TC/GC via Slack or Zoom call, who will vote on the matter. A simple majority suffices for including the SIG. The SIG needs to have at least equal maturity as the project. For instance, if OpenTelemetry’s maturity is set to Beta, the coming SIG has to be at least Beta as well, so that it doesn’t downgrade the main project’s maturity. +SIGs can request to be included in the Tier-1 List by contacting a TC or GC member. The TC/GC member will bring the request to the TC/GC via Slack or Zoom call, who will vote on the matter. A simple majority suffices for including the SIG. The SIG needs to have at least equal maturity as the project. For instance, if OpenTelemetry's maturity is set to Beta, the coming SIG has to be at least Beta as well, so that it doesn't downgrade the main project's maturity. -Components can request project maintainers to be included in the Tier-1 list via a GitHub issue created on the main repository of the SIG. The SIG maintainers will then vote on the matter. A simple majority suffices for including the component. The component needs to have at least equal maturity as the SIG so that it doesn’t downgrade the SIG’s maturity. If SIG maintainers have strong reasons to include a component with a lower status, they can request an exception with the GC/TC. A supermajority vote is required to accept the request until the project reaches the “Stable” level so the project’s scope doesn’t continuously grow. After we reach the “Stable” level, a simple majority decision will be sufficient. +Components can request project maintainers to be included in the Tier-1 list via a GitHub issue created on the main repository of the SIG. The SIG maintainers will then vote on the matter. A simple majority suffices for including the component. The component needs to have at least equal maturity as the SIG so that it doesn't downgrade the SIG's maturity. If SIG maintainers have strong reasons to include a component with a lower status, they can request an exception with the GC/TC. A supermajority vote is required to accept the request until the project reaches the "Stable" level so the project's scope doesn't continuously grow. After we reach the "Stable" level, a simple majority decision will be sufficient. SIGs or components that are seen by the maintainers as critical for the future of the project, like a new signal, are added to the Candidate Tier-1 List. Once this happens, the other Tier-1 SIGs or components need to evaluate whether they need to be changed to accommodate the new candidate. ### Downgrading SIGs and components -While we don’t expect SIGs and components to be downgraded, there may be situations where the evolution of the project or SIG is affected by the inaction of specific SIGs or components. For instance, if a new signal is added to the Candidate Tier-1 List and a SIG fails to adopt this new signal within a reasonable time, the GC/TC may choose to remove the SIG from the project’s Tier-1 List. To do that, two TC/GC members must sponsor the removal proposal, and a supermajority vote (two-thirds) is required to accept the proposal. +While we don't expect SIGs and components to be downgraded, there may be situations where the evolution of the project or SIG is affected by the inaction of specific SIGs or components. For instance, if a new signal is added to the Candidate Tier-1 List and a SIG fails to adopt this new signal within a reasonable time, the GC/TC may choose to remove the SIG from the project's Tier-1 List. To do that, two TC/GC members must sponsor the removal proposal, and a supermajority vote (two-thirds) is required to accept the proposal. -Similarly, if a component becomes unmaintained or isn’t of interest to the SIG maintainers anymore, it can be removed from the Tier-1 List. A simple majority vote by the SIG maintainers is required to accept the proposal. +Similarly, if a component becomes unmaintained or isn't of interest to the SIG maintainers anymore, it can be removed from the Tier-1 List. A simple majority vote by the SIG maintainers is required to accept the proposal. ## Trade-offs and mitigations From 09508789498ff4710fc7aae337fe1a6d5f0a1fd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Fri, 9 Jun 2023 15:06:46 -0300 Subject: [PATCH 03/17] markdown linter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 8c4b708c6..c7d3eb06b 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -2,7 +2,7 @@ On 08 Mar 2023, the OpenTelemetry GC and TC held an OpenTelemetry Leadership summit, discussing various topics. One of the themes we discussed was establishing standard rules for describing the maturity of the OpenTelemetry project. This OTEP summarizes what was discussed there and is intended to have the wider community provide feedback. -This OTEP builds on what was previously communicated by the project, especially on the following page: https://opentelemetry.io/docs/reference/specification/versioning-and-stability. +This OTEP builds on what was previously communicated by the project, especially the [Versioning and stability for OpenTelemetry clients](https://opentelemetry.io/docs/reference/specification/versioning-and-stability). The Collector's [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels) inspired the maturity levels. @@ -79,6 +79,7 @@ When discussing the components' maturity, we often debate what should be include Projects MUST list their Tier-1 Components in the main readme file. A Tier-1 Component MAY be hosted under the project's "contrib" repository. Not all components under the main repository (sometimes called the "core" repository) are automatically Tier-1 Components. A component can be declared "Tier-1" only if they have the following characteristics: + * The component has at least the same maturity level as the SIG * The component has a clear code owner * The code owner is active within the project @@ -91,6 +92,7 @@ Similar to a Tier-1 Component, a Tier-1 Signal must have stable support in order Not all signals will have the same requirements. For instance, Logs might not provide an instrumentation API specification. List of Tier-1 signals and their capabilities: + * Logs * Data model * SDK specification @@ -109,7 +111,7 @@ List of Tier-1 signals and their capabilities: * SDK specification * Instrumentation SDKs -The lifecycle of a signal is defined in the following document: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/ . While the stability and versioning of the signals may relate to this OTEP, the previously linked document specifies the details on how to reach the "stable" level mentioned in this OTEP. +The lifecycle of a signal is defined in the [Versioning and stability for OpenTelemetry clients](https://opentelemetry.io/docs/reference/specification/versioning-and-stability). While the stability and versioning of the signals may relate to this OTEP, the previously linked document specifies the details on how to reach the "stable" level mentioned in this OTEP. The "experimental" level from the signal versioning and stability document relates to the "alpha" and "beta" levels from this OTEP, "stable" and "deprecated" are equivalent to their counterparts on this document, and "removed" is non-existent here. @@ -135,7 +137,7 @@ This approach gives both a top-down and a bottom-up approaches, allowing the GC/ ## Prior art and alternatives -* The specification status has a ["Component Lifecycle"](https://opentelemetry.io/docs/specs/status/) description, with definitions that might overlap with some of the levels listed in this OTEP. +* The specification status has a ["Component Lifecycle"](https://opentelemetry.io/docs/specs/status/) description, with definitions that might overlap with some of the levels listed in this OTEP. * The same page lists the status of the different parts of the spec * The ["Versioning and stability for OpenTelemetry clients"](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#signal-lifecycle) page has a detailed view on the lifecycle of a signal and which general stability guarantees should be expected by OpenTelemetry clients. Notably, it lacks information about maturity of the Collector. This OTEP could be seen as clashing with the last section of that page, "OpenTelemetry GA". But while that page established a point where both OpenTracing and OpenCensus would be considered deprecated, this OTEP here defines the criteria for calling OpenTelemetry "stable" and making that a requirement for a future graduation. This would also make it clear to end-users which parts of the project they can rely on. * The OpenTelemetry Collector has its own [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels), which served as inspiration to the ones here. @@ -146,4 +148,4 @@ None at the moment. ## Future possibilities -This change clears the path for a future graduation, by providing an objective way to evaluate what should be included in the graduation scope. \ No newline at end of file +This change clears the path for a future graduation, by providing an objective way to evaluate what should be included in the graduation scope. From 2c5b0bfce56f798bd7ccb1b507865823a9d4bb78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Wed, 5 Jul 2023 16:08:49 -0300 Subject: [PATCH 04/17] Add a few clarifications based on review round MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index c7d3eb06b..a61b545da 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -8,13 +8,13 @@ The Collector's [stability levels](https://github.com/open-telemetry/opentelemet ## Motivation -Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the project's maturity. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users. +Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the project's maturity. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users. The public message we want to convey by stating that a SIG is a tier-1 SIG is that the SIG has both a healthy community and is seen as critical to the project as a whole. Only once we reach the "stable" level at the project level will we be ready to consider graduating OpenTelemetry at the CNCF, with all of the Tier-1 SIGs being in the context of the graduation, including their Tier-1 Components. This OTEP provides a framework for describing project maturity as a whole. ## Glossary -* *SIG:* an official SIG within the OpenTelemetry project, like the Collector or Java. Some WGs are temporarily accepted, given they should be SIGs instead of WGs, like the Semantic Conventions WG. +* *SIG:* an official SIG within the OpenTelemetry project, like the Collector or Java. Given that some Working Groups (WGs) are effectively SIGs, like the Semantic Conventions WG, WGs will be accepted on an individual basis. * *Tier-1 SIG:* a SIG within the OpenTelemetry project deemed critical by the GC/TC. * *Candidate Tier-1 SIG:* a SIG that is deemed as critical for the future of the project, but might not be of the same maturity level yet. It's expected to reach that level eventually, and other Tier-1 SIGs should be prepared to accommodate the new component as needed. * *Component:* module maintained by a SIG like a Collector exporter or an SDK sampler. @@ -26,7 +26,7 @@ Only once we reach the "stable" level at the project level will we be ready to c ### Maturity levels -SIGs and components of a project MUST have a declared maturity level established by SIG maintainers (SIGs). The maturity level for a SIG or component is, at most, the lowest level of its dependencies or priority components. For instance, if the Collector SIG maintainers declare the "otlpreceiver" component as a tier-1 component of the Collector core distribution, and the "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" can be at most "beta". The OpenTelemetry Collector "core" distribution is also affected so that it can be at most "beta". +SIGs and components of a project MUST have a declared maturity level established by SIG maintainers (SIGs). The maturity of the SIG is assessed by its maintainers, while the maturity of the components might be delegated by the maintainers to code owners. The maturity level for a SIG or component is, at most, the lowest level of its dependencies or priority components. For instance, if the Collector SIG maintainers declare the "otlpreceiver" component as a tier-1 component of the Collector core distribution, and the "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" can be at most "beta". The OpenTelemetry Collector "core" distribution is also affected so that it can be at most "beta". Only once all dependencies are marked as "stable" MAY a component be marked as "stable". Only once all Tier-1 Components of a SIG are "stable" MAY that SIG be marked as "stable". @@ -64,17 +64,19 @@ This OTEP recommends the following SIGs to be included as part of the Tier-1 SIG * Spec General * Semantic Conventions (WG) +* Collector * Java -* Java auto-instrumentation * Go -* .Net +* .NET * JavaScript Once this OTEP is approved, the TC and GC members will vote on the individual SIGs from the list above and are free to make further suggestions. A final list of Tier-1 SIGs shall be in the "community" repository. ### Tier-1 Components -When discussing the components' maturity, we often debate what should be included in the evaluation criteria. To help clarify that, we introduce the concept of "Tier-1 SIGs" and "Tier-1 Components". Tier-1 Components are critical for a specific SIG: only when all Tier-1 Components are stable can a project be evaluated as stable. For instance, the "OTLP receiver" for the OpenTelemetry Collector could potentially be a "Tier-1 Component". Only after this component is declared stable may the Collector be declared stable, provided all other Tier-1 Components are also stable. +When discussing the components' maturity, we often debate what should be included in the evaluation criteria. To help clarify that, we introduce the concept of "Tier-1 SIGs" and "Tier-1 Components". Tier-1 Components are critical for a specific SIG: only when all Tier-1 Components are stable can a project be evaluated as stable. Example: + +* The "OTLP receiver" for the OpenTelemetry Collector could potentially be a "Tier-1 Component". Only after this component is declared stable may the Collector be declared stable, provided all other Tier-1 Components are also stable. Projects MUST list their Tier-1 Components in the main readme file. A Tier-1 Component MAY be hosted under the project's "contrib" repository. Not all components under the main repository (sometimes called the "core" repository) are automatically Tier-1 Components. From fb08dbf36fd52500cce893eb811f6361441fa826 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Fri, 7 Jul 2023 16:14:26 -0300 Subject: [PATCH 05/17] s/priority/tier-1 Co-authored-by: Anthony Mirabella --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index a61b545da..f60e0f717 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -117,7 +117,7 @@ The lifecycle of a signal is defined in the [Versioning and stability for OpenTe The "experimental" level from the signal versioning and stability document relates to the "alpha" and "beta" levels from this OTEP, "stable" and "deprecated" are equivalent to their counterparts on this document, and "removed" is non-existent here. -When a new signal reaches the "stable" level, OpenTelemetry TC and GC will ultimately decide whether to include it as part of OpenTelemetry's priority components, using the process described in [Promoting SIGs and components](#promoting-sigs-and-components). +When a new signal reaches the "stable" level, OpenTelemetry TC and GC will ultimately decide whether to include it as part of OpenTelemetry's Tier-1 components, using the process described in [Promoting SIGs and components](#promoting-sigs-and-components). ### Promoting SIGs and components From d9085202e794df16ed292a7be8cba1fa8fbc97b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Mon, 10 Jul 2023 15:35:48 -0300 Subject: [PATCH 06/17] Remove super majority wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index f60e0f717..9c21f4f79 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -123,7 +123,7 @@ When a new signal reaches the "stable" level, OpenTelemetry TC and GC will ultim SIGs can request to be included in the Tier-1 List by contacting a TC or GC member. The TC/GC member will bring the request to the TC/GC via Slack or Zoom call, who will vote on the matter. A simple majority suffices for including the SIG. The SIG needs to have at least equal maturity as the project. For instance, if OpenTelemetry's maturity is set to Beta, the coming SIG has to be at least Beta as well, so that it doesn't downgrade the main project's maturity. -Components can request project maintainers to be included in the Tier-1 list via a GitHub issue created on the main repository of the SIG. The SIG maintainers will then vote on the matter. A simple majority suffices for including the component. The component needs to have at least equal maturity as the SIG so that it doesn't downgrade the SIG's maturity. If SIG maintainers have strong reasons to include a component with a lower status, they can request an exception with the GC/TC. A supermajority vote is required to accept the request until the project reaches the "Stable" level so the project's scope doesn't continuously grow. After we reach the "Stable" level, a simple majority decision will be sufficient. +Components can request project maintainers to be included in the Tier-1 list via a GitHub issue created on the main repository of the SIG. The SIG maintainers will then vote on the matter. A simple majority suffices for including the component. The component needs to have at least equal maturity as the SIG so that it doesn't downgrade the SIG's maturity. If SIG maintainers have strong reasons to include a component with a lower status, they can request an exception with the GC/TC. A simple majority is required to accept the request. SIGs or components that are seen by the maintainers as critical for the future of the project, like a new signal, are added to the Candidate Tier-1 List. Once this happens, the other Tier-1 SIGs or components need to evaluate whether they need to be changed to accommodate the new candidate. From c4df80a03f98d75b307631742acab5ee52168fc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Tue, 11 Jul 2023 10:23:41 -0300 Subject: [PATCH 07/17] Components in development may be removed without prior notice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 9c21f4f79..ee5fb984f 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -32,7 +32,7 @@ Only once all dependencies are marked as "stable" MAY a component be marked as " #### Development -Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, ...). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. +Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, ...). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. #### Alpha From 129f863082f281adbedda6be728c7766dcb7f7b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Fri, 14 Jul 2023 16:49:59 -0300 Subject: [PATCH 08/17] Remove the notion of tiers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 107 +++------------------------------- 1 file changed, 8 insertions(+), 99 deletions(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index ee5fb984f..dd6a6701b 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -1,4 +1,4 @@ -# Framework for defining the maturity of OpenTelemetry and its SIGs +# Definition of maturity levels to be uniformly used by OpenTelemetry SIGs On 08 Mar 2023, the OpenTelemetry GC and TC held an OpenTelemetry Leadership summit, discussing various topics. One of the themes we discussed was establishing standard rules for describing the maturity of the OpenTelemetry project. This OTEP summarizes what was discussed there and is intended to have the wider community provide feedback. @@ -8,27 +8,13 @@ The Collector's [stability levels](https://github.com/open-telemetry/opentelemet ## Motivation -Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the project's maturity. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users. The public message we want to convey by stating that a SIG is a tier-1 SIG is that the SIG has both a healthy community and is seen as critical to the project as a whole. - -Only once we reach the "stable" level at the project level will we be ready to consider graduating OpenTelemetry at the CNCF, with all of the Tier-1 SIGs being in the context of the graduation, including their Tier-1 Components. This OTEP provides a framework for describing project maturity as a whole. - -## Glossary - -* *SIG:* an official SIG within the OpenTelemetry project, like the Collector or Java. Given that some Working Groups (WGs) are effectively SIGs, like the Semantic Conventions WG, WGs will be accepted on an individual basis. -* *Tier-1 SIG:* a SIG within the OpenTelemetry project deemed critical by the GC/TC. -* *Candidate Tier-1 SIG:* a SIG that is deemed as critical for the future of the project, but might not be of the same maturity level yet. It's expected to reach that level eventually, and other Tier-1 SIGs should be prepared to accommodate the new component as needed. -* *Component:* module maintained by a SIG like a Collector exporter or an SDK sampler. -* *Tier-1 Component:* a component selected by project maintainers as critical for the SIG. For instance, the OTLP receiver will likely be selected as a Tier-1 Component of the Collector. See Tier-1 Components for more details. -* *Candidate Tier-1 Component:* similar to "Candidate Tier-1 SIG", but for a component within a SIG. -* *Dependency:* an OpenTelemetry SIG or component that is required by another SIG or component. For instance, the OTLP Logs Data Model from the Spec is required for the Collector's Logging support. +Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the maturity for components delivered by SIGs in the name of the project. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users using a unified nomenclature. ## Explanation ### Maturity levels -SIGs and components of a project MUST have a declared maturity level established by SIG maintainers (SIGs). The maturity of the SIG is assessed by its maintainers, while the maturity of the components might be delegated by the maintainers to code owners. The maturity level for a SIG or component is, at most, the lowest level of its dependencies or priority components. For instance, if the Collector SIG maintainers declare the "otlpreceiver" component as a tier-1 component of the Collector core distribution, and the "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" can be at most "beta". The OpenTelemetry Collector "core" distribution is also affected so that it can be at most "beta". - -Only once all dependencies are marked as "stable" MAY a component be marked as "stable". Only once all Tier-1 Components of a SIG are "stable" MAY that SIG be marked as "stable". +Deliverables of a SIG MUST have a declared maturity level, established by SIG maintainers (SIGs), likely with the input of the code owners. The maturity level of a deliverable is, at most, the lowest level of the user-visible dependencies. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" can be at most "beta". The OpenTelemetry Collector "core" distribution is also affected so that it can be at most "beta". Only once all dependencies are marked as "stable" MAY a component be marked as "stable". #### Development @@ -54,88 +40,9 @@ Development of this component is halted, and no further support will be provided A component identified as unmaintained does not have an active code owner. Such components may have never been assigned a code owner, or a previously active code owner has not responded to requests for feedback within 6 weeks of being contacted. Issues and pull requests for unmaintained components SHOULD be labeled as such. After 6 months of being unmaintained, these components MAY be deprecated. Unmaintained components are actively seeking contributors to become code owners. -### Specification requirements - -The specification should declare all requirements for a specified component to be declared stable. When implementations are still missing features required by the specification, they can be at most Alpha status. - -### Tier-1 SIGs - -This OTEP recommends the following SIGs to be included as part of the Tier-1 SIGs for OpenTelemetry: - -* Spec General -* Semantic Conventions (WG) -* Collector -* Java -* Go -* .NET -* JavaScript - -Once this OTEP is approved, the TC and GC members will vote on the individual SIGs from the list above and are free to make further suggestions. A final list of Tier-1 SIGs shall be in the "community" repository. - -### Tier-1 Components - -When discussing the components' maturity, we often debate what should be included in the evaluation criteria. To help clarify that, we introduce the concept of "Tier-1 SIGs" and "Tier-1 Components". Tier-1 Components are critical for a specific SIG: only when all Tier-1 Components are stable can a project be evaluated as stable. Example: - -* The "OTLP receiver" for the OpenTelemetry Collector could potentially be a "Tier-1 Component". Only after this component is declared stable may the Collector be declared stable, provided all other Tier-1 Components are also stable. - -Projects MUST list their Tier-1 Components in the main readme file. A Tier-1 Component MAY be hosted under the project's "contrib" repository. Not all components under the main repository (sometimes called the "core" repository) are automatically Tier-1 Components. - -A component can be declared "Tier-1" only if they have the following characteristics: - -* The component has at least the same maturity level as the SIG -* The component has a clear code owner -* The code owner is active within the project -* The maintainers of the project are comfortable supporting the component should the code owner decide to step down or leave the project - -### Tier-1 Signals - -Similar to a Tier-1 Component, a Tier-1 Signal must have stable support in order to declare OpenTelemetry as stable. Declaring a signal as Tier-1 means that all projects must also see that signal as required for declaring the project stable. - -Not all signals will have the same requirements. For instance, Logs might not provide an instrumentation API specification. - -List of Tier-1 signals and their capabilities: - -* Logs - * Data model - * SDK specification - * Instrumentation SDKs - * Bridge API specification -* Metrics - * Data model - * API specification - * Instrumentation APIs - * SDK specification - * Instrumentation SDKs -* Traces - * Data model - * API specification - * Instrumentation APIs - * SDK specification - * Instrumentation SDKs - -The lifecycle of a signal is defined in the [Versioning and stability for OpenTelemetry clients](https://opentelemetry.io/docs/reference/specification/versioning-and-stability). While the stability and versioning of the signals may relate to this OTEP, the previously linked document specifies the details on how to reach the "stable" level mentioned in this OTEP. - -The "experimental" level from the signal versioning and stability document relates to the "alpha" and "beta" levels from this OTEP, "stable" and "deprecated" are equivalent to their counterparts on this document, and "removed" is non-existent here. - -When a new signal reaches the "stable" level, OpenTelemetry TC and GC will ultimately decide whether to include it as part of OpenTelemetry's Tier-1 components, using the process described in [Promoting SIGs and components](#promoting-sigs-and-components). - -### Promoting SIGs and components - -SIGs can request to be included in the Tier-1 List by contacting a TC or GC member. The TC/GC member will bring the request to the TC/GC via Slack or Zoom call, who will vote on the matter. A simple majority suffices for including the SIG. The SIG needs to have at least equal maturity as the project. For instance, if OpenTelemetry's maturity is set to Beta, the coming SIG has to be at least Beta as well, so that it doesn't downgrade the main project's maturity. - -Components can request project maintainers to be included in the Tier-1 list via a GitHub issue created on the main repository of the SIG. The SIG maintainers will then vote on the matter. A simple majority suffices for including the component. The component needs to have at least equal maturity as the SIG so that it doesn't downgrade the SIG's maturity. If SIG maintainers have strong reasons to include a component with a lower status, they can request an exception with the GC/TC. A simple majority is required to accept the request. - -SIGs or components that are seen by the maintainers as critical for the future of the project, like a new signal, are added to the Candidate Tier-1 List. Once this happens, the other Tier-1 SIGs or components need to evaluate whether they need to be changed to accommodate the new candidate. - -### Downgrading SIGs and components - -While we don't expect SIGs and components to be downgraded, there may be situations where the evolution of the project or SIG is affected by the inaction of specific SIGs or components. For instance, if a new signal is added to the Candidate Tier-1 List and a SIG fails to adopt this new signal within a reasonable time, the GC/TC may choose to remove the SIG from the project's Tier-1 List. To do that, two TC/GC members must sponsor the removal proposal, and a supermajority vote (two-thirds) is required to accept the proposal. - -Similarly, if a component becomes unmaintained or isn't of interest to the SIG maintainers anymore, it can be removed from the Tier-1 List. A simple majority vote by the SIG maintainers is required to accept the proposal. - ## Trade-offs and mitigations -This approach gives both a top-down and a bottom-up approaches, allowing the GC/TC to determine what are the Tier-1 SIGs for OpenTelemetry as a whole, while still allowing SIG maintainers to determine what's in scope within their areas of expertise. +This OTEP allows SIG maintainers to declare the maturity of the SIG's deliverables without declaring which ones are key for OpenTelemetry. When, and if, this is needed, a new OTEP may be created using the maturity levels as a possible framework. ## Prior art and alternatives @@ -146,8 +53,10 @@ This approach gives both a top-down and a bottom-up approaches, allowing the GC/ ## Open questions -None at the moment. +* Deliverables such as the Collector Contrib binary and the Java Agent ship with more components than what the SIGs might be comfortable marking as stable. Despite this, there's a desire to mark the deliverables as stable. Would it be sufficient require the SIGs to mark which components are stable? +* Should SDKs be required to fully implement the specification before they can be marked as stable? +* Should this OTEP define a file name to be adopted by all repositories to declare their deliverables and their maturity levels? ## Future possibilities -This change clears the path for a future graduation, by providing an objective way to evaluate what should be included in the graduation scope. +Once the maturity levels are widely adopted, the GC/TC might decide to pick and choose components from different SIGs and proceed with a graduation proposal within the CNCF. The decision framework for choosing the components will be defined at a later stage. From 4fa94d47743d513120afb4fe0b7d8698469c5aff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Thu, 24 Aug 2023 12:45:00 -0300 Subject: [PATCH 09/17] Another round of reviews MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index dd6a6701b..40eb1c9c3 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -14,7 +14,11 @@ Quite often, the community is faced with the question of the quality and maturit ### Maturity levels -Deliverables of a SIG MUST have a declared maturity level, established by SIG maintainers (SIGs), likely with the input of the code owners. The maturity level of a deliverable is, at most, the lowest level of the user-visible dependencies. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" can be at most "beta". The OpenTelemetry Collector "core" distribution is also affected so that it can be at most "beta". Only once all dependencies are marked as "stable" MAY a component be marked as "stable". +Deliverables of a SIG MUST have a declared maturity level, established by SIG maintainers (SIGs), likely with the input of the code owners. While the main deliverable can have a specific maturity level, individual components might have a different one. Examples: +* the Collector core distribution might declare itself stable and include a receiver that is not stable. In that case, the receiver has to be clearly marked as such +* the Java Agent might be declared stable, while individual instrumentation packages are not + +It is recommended that components should not be marked as stable if their user-visible interfaces are not stable. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" should be at most "beta". Maintainers are free to deviate from this recommendation if they believe users are not going to be affected by future changes. #### Development @@ -22,12 +26,16 @@ Not all pieces of the component are in place yet, and it might not be available #### Alpha -This is the default level: any components with no explicit maturity level should be assumed to be "Alpha". The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The configuration options might often change without backward compatibility guarantees. +This is the default level: any components with no explicit maturity level should be assumed to be "Alpha". The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The component's interface and configuration options might often change without backward compatibility guarantees. Components at this stage might be dropped at any time without notice. #### Beta Same as Alpha, but the interfaces (API, configuration, generated telemetry) are treated as stable whenever possible. While there might be breaking changes between releases, component owners should try to minimize them. A component at this stage is expected to have had exposure to non-critical production workloads already during its Alpha phase, making it suitable for broader usage. +#### Feature freeze + +The component is feature-complete and ready for broader usage. The component is ready to be declared stable, it might just need to be tested in more production environments before that can happen. Bugs and performance problems are expected to be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are not expected to happen without prior notice unless under special circumstances. + #### Stable The component is ready for general availability. Bugs and performance problems should be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are not expected to happen without prior notice unless under special circumstances. @@ -53,8 +61,7 @@ This OTEP allows SIG maintainers to declare the maturity of the SIG's deliverabl ## Open questions -* Deliverables such as the Collector Contrib binary and the Java Agent ship with more components than what the SIGs might be comfortable marking as stable. Despite this, there's a desire to mark the deliverables as stable. Would it be sufficient require the SIGs to mark which components are stable? -* Should SDKs be required to fully implement the specification before they can be marked as stable? +* Should SDKs be required to fully implement the specification before they can be marked as stable? See [open-telemetry/opentelemetry-specification#3673](https://github.com/open-telemetry/opentelemetry-specification/issues/3673) * Should this OTEP define a file name to be adopted by all repositories to declare their deliverables and their maturity levels? ## Future possibilities From 2706e1d2da1edc2e39dcb600d7b92c942f963f90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Tue, 12 Sep 2023 06:50:09 -0300 Subject: [PATCH 10/17] further clarifications MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 40eb1c9c3..79a71e3ca 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -8,21 +8,22 @@ The Collector's [stability levels](https://github.com/open-telemetry/opentelemet ## Motivation -Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the maturity for components delivered by SIGs in the name of the project. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users using a unified nomenclature. +Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the maturity for SIG deliverables in the name of the project. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users using a unified nomenclature. ## Explanation ### Maturity levels Deliverables of a SIG MUST have a declared maturity level, established by SIG maintainers (SIGs), likely with the input of the code owners. While the main deliverable can have a specific maturity level, individual components might have a different one. Examples: + * the Collector core distribution might declare itself stable and include a receiver that is not stable. In that case, the receiver has to be clearly marked as such * the Java Agent might be declared stable, while individual instrumentation packages are not -It is recommended that components should not be marked as stable if their user-visible interfaces are not stable. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" should be at most "beta". Maintainers are free to deviate from this recommendation if they believe users are not going to be affected by future changes. +Components should not be marked as stable if their user-visible interfaces are not stable. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" should be at most "beta". Maintainers are free to deviate from this recommendation if they believe users are not going to be affected by future changes. #### Development -Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, ...). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. +Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, and so on). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. #### Alpha @@ -42,7 +43,7 @@ The component is ready for general availability. Bugs and performance problems s #### Deprecated -Development of this component is halted, and no further support will be provided. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed. +Development of this component is halted, and no further support will be provided. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed, either in terms of a concrete version number or the date of a release, like: "the first release after 2023-08-01". #### Unmaintained From f5934abcb7f200dbad666575e872e8f653927021 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Tue, 12 Sep 2023 08:12:53 -0300 Subject: [PATCH 11/17] sig deliverables and components MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 79a71e3ca..48a1bab45 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -8,7 +8,7 @@ The Collector's [stability levels](https://github.com/open-telemetry/opentelemet ## Motivation -Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the maturity for SIG deliverables in the name of the project. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users using a unified nomenclature. +Quite often, the community is faced with the question of the quality and maturity expectations of its diverse set of components. This OTEP aims to bring clarity by establishing a framework to communicate the maturity for SIG deliverables and components in the name of the project. As the OpenTelemetry project comprises a multitude of SIGs, and each SIG has several components of varying quality, having this framework will help set the right expectations for OpenTelemetry users using a unified nomenclature. ## Explanation From 64f2ef7a676b32343d26efea45b3ede2ee37db26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Mon, 25 Sep 2023 09:57:08 -0300 Subject: [PATCH 12/17] Renamed to release candidate, add breaking change definition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 48a1bab45..e57ba8dde 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -21,6 +21,8 @@ Deliverables of a SIG MUST have a declared maturity level, established by SIG ma Components should not be marked as stable if their user-visible interfaces are not stable. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" should be at most "beta". Maintainers are free to deviate from this recommendation if they believe users are not going to be affected by future changes. +For the purposes of this document, a breaking change is defined as a change that may require consumers of our components to adapt themselves in order to avoid disruption to their usage of our components. + #### Development Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, and so on). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. @@ -33,7 +35,7 @@ This is the default level: any components with no explicit maturity level should Same as Alpha, but the interfaces (API, configuration, generated telemetry) are treated as stable whenever possible. While there might be breaking changes between releases, component owners should try to minimize them. A component at this stage is expected to have had exposure to non-critical production workloads already during its Alpha phase, making it suitable for broader usage. -#### Feature freeze +#### Release Candidate The component is feature-complete and ready for broader usage. The component is ready to be declared stable, it might just need to be tested in more production environments before that can happen. Bugs and performance problems are expected to be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are not expected to happen without prior notice unless under special circumstances. From f574bc294c02174b155f126c1b99c502aa176c06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Wed, 4 Oct 2023 07:41:52 -0300 Subject: [PATCH 13/17] s/should not/SHOULD NOT/ Co-authored-by: Dmitrii Anoshin --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index e57ba8dde..0bd8c633e 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -19,7 +19,7 @@ Deliverables of a SIG MUST have a declared maturity level, established by SIG ma * the Collector core distribution might declare itself stable and include a receiver that is not stable. In that case, the receiver has to be clearly marked as such * the Java Agent might be declared stable, while individual instrumentation packages are not -Components should not be marked as stable if their user-visible interfaces are not stable. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" should be at most "beta". Maintainers are free to deviate from this recommendation if they believe users are not going to be affected by future changes. +Components SHOULD NOT be marked as stable if their user-visible interfaces are not stable. For instance, if the Collector's component "otlpreceiver" declares a dependency on the OpenTelemetry Collector API "config" package which is marked with a maturity level of "beta", the "otlpreceiver" should be at most "beta". Maintainers are free to deviate from this recommendation if they believe users are not going to be affected by future changes. For the purposes of this document, a breaking change is defined as a change that may require consumers of our components to adapt themselves in order to avoid disruption to their usage of our components. From 904b3b82efa1347fb5d24644d30f8d03fb26aded Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Thu, 5 Oct 2023 07:32:43 -0300 Subject: [PATCH 14/17] Clarify breaking changes under special circumstances MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 0bd8c633e..e38836bb2 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -37,11 +37,11 @@ Same as Alpha, but the interfaces (API, configuration, generated telemetry) are #### Release Candidate -The component is feature-complete and ready for broader usage. The component is ready to be declared stable, it might just need to be tested in more production environments before that can happen. Bugs and performance problems are expected to be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are not expected to happen without prior notice unless under special circumstances. +The component is feature-complete and ready for broader usage. The component is ready to be declared stable, it might just need to be tested in more production environments before that can happen. Bugs and performance problems are expected to be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are only allowed under special circumstances. Whenever possible, users should be given prior notice of the breaking changes. #### Stable -The component is ready for general availability. Bugs and performance problems should be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are not expected to happen without prior notice unless under special circumstances. +The component is ready for general availability. Bugs and performance problems should be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are only allowed under special circumstances. Whenever possible, users should be given prior notice of the breaking changes. #### Deprecated From 24035268a8b51182ff2460033ee18b55253ea49c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Thu, 19 Oct 2023 09:37:01 -0300 Subject: [PATCH 15/17] expand what we want as feedback around UX for components under development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index e38836bb2..574adb9ae 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -25,7 +25,7 @@ For the purposes of this document, a breaking change is defined as a change that #### Development -Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback is desired, especially regarding the user experience (configuration options, component observability, technical implementation details, and so on). Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. +Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback around the UX of the component is desired, such as for configuration options, component observability, technical implementation details, and planned use-cases for the component. Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. #### Alpha From fe37de326d161c62dbd3665800735ae120a09d1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Tue, 12 Dec 2023 15:19:44 +0100 Subject: [PATCH 16/17] Add further prior art MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 574adb9ae..7fb66a200 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -61,6 +61,8 @@ This OTEP allows SIG maintainers to declare the maturity of the SIG's deliverabl * The same page lists the status of the different parts of the spec * The ["Versioning and stability for OpenTelemetry clients"](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#signal-lifecycle) page has a detailed view on the lifecycle of a signal and which general stability guarantees should be expected by OpenTelemetry clients. Notably, it lacks information about maturity of the Collector. This OTEP could be seen as clashing with the last section of that page, "OpenTelemetry GA". But while that page established a point where both OpenTracing and OpenCensus would be considered deprecated, this OTEP here defines the criteria for calling OpenTelemetry "stable" and making that a requirement for a future graduation. This would also make it clear to end-users which parts of the project they can rely on. * The OpenTelemetry Collector has its own [stability levels](https://github.com/open-telemetry/opentelemetry-collector#stability-levels), which served as inspiration to the ones here. +* [Definition of documentation states](https://opentelemetry.io/docs/specs/otel/document-status/) +* [Telemetry stability](https://opentelemetry.io/docs/specs/otel/telemetry-stability/) (uses unstable instead of experimental) ## Open questions From a1009a23c034d3ac2b8ecd8577f21ce47f0a42c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Tue, 12 Dec 2023 15:20:47 +0100 Subject: [PATCH 17/17] removed 'no further support fill be provided' from deprecated MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling --- text/0232-maturity-of-otel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0232-maturity-of-otel.md b/text/0232-maturity-of-otel.md index 7fb66a200..3ce9726f7 100644 --- a/text/0232-maturity-of-otel.md +++ b/text/0232-maturity-of-otel.md @@ -45,7 +45,7 @@ The component is ready for general availability. Bugs and performance problems s #### Deprecated -Development of this component is halted, and no further support will be provided. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed, either in terms of a concrete version number or the date of a release, like: "the first release after 2023-08-01". +Development of this component is halted. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed, either in terms of a concrete version number or the date of a release, like: "the first release after 2023-08-01". #### Unmaintained