Add guidelines for metric graduation

Co-authored-by: Marek Siarkowicz <[email protected]>

Author: richabanker

contributors/devel/sig-instrumentation/metric-instrumentation.md

@@ -22,6 +22,8 @@ internal and external.
 
 ## Quick Start
 
+### Adding a New Metric
+
 The following describes the basic steps required to add a new metric (in Go).
 
 1. Import "k8s.io/component-base/metrics" for metrics and "k8s.io/component-base/metrics/legacyregistry" to register your declared metrics.
@@ -67,6 +69,31 @@ first calling WithLabelValues if your metric has any labels
   	requestCounter.WithLabelValues(*verb, *resource, client, strconv.Itoa(*httpCode)).Inc()
    ```
 
+### Graduating an Existing Metric
+
+When graduating a metric from Alpha to Beta or from Beta to Stable, the following requirements must be met. For more information on stability levels and their guarantees, see [Metrics Stability](#metrics-stability).
+
+#### Graduating to Beta
+
+1. **Testing requirement**: The metric must have a corresponding test that validates:
+   - The metric is registered and emitted correctly
+   - The metric has the expected labels and values under known conditions
+
+2. **Documentation**: Ensure the metric has a clear and accurate help text description.
+
+3. **API Review**: Graduating a metric to Beta requires an API review by SIG Instrumentation, as it represents a contractual API agreement. See the [API Review](/contributors/devel/sig-instrumentation/metric-stability.md#api-review) section in the metrics stability documentation.
+
+#### Graduating to Stable
+
+The metric must meet all of the requirements for Beta graduation.
+
+1. **Testing requirement**:
+   - The metric must be included in the [stable metrics list](https://github.com/kubernetes/kubernetes/blob/master/test/instrumentation/testdata/stable-metrics-list.yaml)
+     - See the [instrumentation test README](https://github.com/kubernetes/kubernetes/tree/master/test/instrumentation/README.md) for steps on how to generate this file correctly
+
+2. **Stability validation**: The metric should have been at Beta stability for at least one release to ensure it has been sufficiently validated in production environments.
+
+3. **API Review**: Marking a metric as stable is a commitment by the owning SIG to maintain stability guarantees. The owning SIG leads must review and approve the graduation first. Additionally, approval from SIG Instrumentation is required as it represents a contractual API agreement. See the [API Review](/contributors/devel/sig-instrumentation/metric-stability.md#api-review) section in the metrics stability documentation.
 
 ## Instrumentation types
 

contributors/devel/sig-instrumentation/metric-stability.md

@@ -48,7 +48,11 @@ From an ingestion point of view, it is backwards-compatible to add or remove pos
 
 ## API Review
 
-Graduating a metric to a stable state is a contractual API agreement, as such, it would be desirable to require an api-review (to sig-instrumentation) for graduating or deprecating a metric (in line with current Kubernetes [api-review processes](https://github.com/kubernetes/community/blob/master/sig-architecture/api-review-process.md)).
+Graduating a metric to beta or stable is a contractual API agreement (in line with current Kubernetes [api-review processes](https://github.com/kubernetes/community/blob/master/sig-architecture/api-review-process.md)).
+
+For **Beta** metrics, approval from SIG Instrumentation is required.
+
+For **Stable** metrics, marking a metric as stable is a commitment by the owning SIG to maintain stability guarantees. The owning SIG leads must review and approve the graduation first. Additionally, approval from SIG Instrumentation is required.
 
 We use a verification script to flag stable metric changes for review by SIG Instrumentation approvers.