[chore][docs/component-stability.md] Add documentation requirements for components based on their stability level (#11871)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

<!-- Issue number if applicable -->

Adds requirements for documentation for different stability levels.

I expect many of these will be done through automation over time :)

#### Link to tracking issue

Fixes #11852
This commit is contained in:
Pablo Baeyens 2025-01-22 16:59:29 +00:00 committed by GitHub
parent f70a4b158d
commit 54c3cd8596
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 37 additions and 0 deletions

View File

@ -32,6 +32,10 @@ required for alpha components, although it is still recommended.
- when removing a configuration option, components MAY keep the old option for a few minor releases and log a WARN level
message instructing users to remove the option.
#### Documentation requirements
Alpha components should document how to use them in the most common situations, including:
- One or more example configuration snippets for the most common use cases.
### Beta
@ -58,6 +62,21 @@ When renaming or removing a configuration option:
Additionally, when removing an option:
- the option MAY be made non-operational already by the same version where it is deprecated
#### Documentation requirements
Beta components should have a set of documentation that documents its usage in most cases,
including:
- One or more example configuration snippets for the most common use cases.
- Advanced configuration options that are known to be used in common environments.
- All component-specific feature gates including a description for them and when they should be
used.
- Warnings about known limitations and ways to misuse the component.
Receivers that produce a fixed set of telemetry should document the telemetry they produce,
including:
- For all signals, the resource attributes that are expected to be present in telemetry.
- For metrics, the name, description, type, units and attributes of each metric.
### 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.
@ -68,6 +87,24 @@ Stable components MUST be compatible between minor versions unless critical secu
component owner MUST provide a migration path and a reasonable time frame for users to upgrade. The same rules from beta
components apply to stable when it comes to configuration changes.
#### Documentation requirements
Stable components should have a complete set of documentation, including:
- One or more example configuration snippets for the most common use cases.
- All configuration options supported by the component and a description for each of them.
- All component-specific feature gates including a description for them and when they should be
used.
- All component-specific self-observability features that are not available for other components and
what they provide.
- Compatibility guarantees with external dependencies including the versions it is compatible with
and under what conditions.
- Warnings about known limitations and ways to misuse the component.
Receivers that produce a fixed set of telemetry should document the telemetry they produce,
including:
- For all signals, the resource attributes that are expected to be present in telemetry.
- For metrics, the name, description, type, units and attributes of each metric.
#### Observability requirements
Stable components should emit enough internal telemetry to let users detect errors, as well as data