[mdatagen] Add deprecation date and migration note per signal

Signed-off-by: ChrsMark <[email protected]>

.chloggen/mdatagen_deprecation_fields.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add deprecation date and migration guide fields as part of component metadata
+
+# One or more tracking issues or pull requests related to the change
+issues: [12359]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

cmd/mdatagen/internal/command_test.go

@@ -299,6 +299,7 @@ func TestInlineReplace(t *testing.T) {
 		componentClass string
 		warnings       []string
 		stability      map[component.StabilityLevel][]string
+		deprecation    map[string]DeprecationInfo
 		distros        []string
 		codeowners     *Codeowners
 		githubProject  string
@@ -436,6 +437,29 @@ Some info about a component
 			},
 			distros: []string{"contrib"},
 		},
+		{
+			name: "readme with multiple signals and deprecation",
+			markdown: `# Some component
+
+<!-- status autogenerated section -->
+<!-- end autogenerated section -->
+
+Some info about a component
+`,
+			outputFile: "readme_with_multiple_signals_and_deprecation.md",
+			stability: map[component.StabilityLevel][]string{
+				component.StabilityLevelBeta:       {"metrics"},
+				component.StabilityLevelAlpha:      {"logs"},
+				component.StabilityLevelDeprecated: {"traces"},
+			},
+			deprecation: DeprecationMap{
+				"traces": DeprecationInfo{
+					Date:      "2025-02-05",
+					Migration: "no migration needed",
+				},
+			},
+			distros: []string{"contrib"},
+		},
 		{
 			name: "readme with cmd class",
 			markdown: `# Some component
@@ -470,6 +494,7 @@ Some info about a component
 					Class:         tt.componentClass,
 					Warnings:      tt.warnings,
 					Codeowners:    tt.codeowners,
+					Deprecation:   tt.deprecation,
 				},
 			}
 			tmpdir := t.TempDir()

cmd/mdatagen/internal/loader_test.go

@@ -32,8 +32,15 @@ func TestLoadMetadata(t *testing.T) {
 						component.StabilityLevelDevelopment: {"logs"},
 						component.StabilityLevelBeta:        {"traces"},
 						component.StabilityLevelStable:      {"metrics"},
+						component.StabilityLevelDeprecated:  {"profiles"},
 					},
 					Distributions: []string{},
+					Deprecation: DeprecationMap{
+						"profiles": DeprecationInfo{
+							Date:      "2025-02-05",
+							Migration: "no migration needed",
+						},
+					},
 					Codeowners: &Codeowners{
 						Active: []string{"dmitryax"},
 					},

cmd/mdatagen/internal/metadata_test.go

@@ -37,6 +37,22 @@ func TestValidate(t *testing.T) {
 			name:    "testdata/no_stability.yaml",
 			wantErr: "missing stability",
 		},
+		{
+			name:    "testdata/no_deprecation_info.yaml",
+			wantErr: "deprecated component missing date and migration guide: traces",
+		},
+		{
+			name:    "testdata/no_deprecation_date_info.yaml",
+			wantErr: "deprecated component missing date in YYYY-MM-DD format: traces",
+		},
+		{
+			name:    "testdata/no_deprecation_migration_info.yaml",
+			wantErr: "deprecated component missing migration guide: traces",
+		},
+		{
+			name:    "testdata/deprecation_info_invalid_date.yaml",
+			wantErr: "deprecated component missing valid date in YYYY-MM-DD format: traces",
+		},
 		{
 			name:    "testdata/invalid_stability.yaml",
 			wantErr: "decoding failed due to the following error(s):\n\nerror decoding 'status.stability': unsupported stability level: \"incorrectstability\"",

cmd/mdatagen/internal/samplereceiver/README.md

@@ -3,18 +3,24 @@ This receiver is used for testing purposes to check the output of mdatagen.
 <!-- status autogenerated section -->
 | Status        |           |
 | ------------- |-----------|
-| Stability     | [development]: logs   |
+| Stability     | [deprecated]: profiles   |
+|               | [development]: logs   |
 |               | [beta]: traces   |
 |               | [stable]: metrics   |
+| Deprecation of profiles | [Date]: 2025-02-05   |
+|                      | [Migration Note]: no migration needed   |
 | Unsupported Platforms | freebsd, illumos |
 | Distributions | [] |
 | Warnings      | [Any additional information that should be brought to the consumer's attention](#warnings) |
 | Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector?query=is%3Aissue%20is%3Aopen%20label%3Areceiver%2Fsample%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector/issues?q=is%3Aopen+is%3Aissue+label%3Areceiver%2Fsample) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector?query=is%3Aissue%20is%3Aclosed%20label%3Areceiver%2Fsample%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector/issues?q=is%3Aclosed+is%3Aissue+label%3Areceiver%2Fsample) |
 | [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@dmitryax](https://www.github.com/dmitryax) |
 
+[deprecated]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecated
 [development]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#development
 [beta]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#beta
 [stable]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#stable
+[Date]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
+[Migration Note]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
 <!-- end autogenerated section -->
 
 ## Warnings

cmd/mdatagen/internal/samplereceiver/metadata.yaml

@@ -12,6 +12,11 @@ status:
     development: [logs]
     beta: [traces]
     stable: [metrics]
+    deprecated: [profiles]
+  deprecation:
+    profiles:
+      migration: "no migration needed"
+      date: "2025-02-05"
   distributions: []
   unsupported_platforms: [freebsd, illumos]
   codeowners:

cmd/mdatagen/internal/status.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"sort"
+	"time"
 
 	"go.opentelemetry.io/collector/component"
 )
@@ -40,12 +41,13 @@ type Codeowners struct {
 }
 
 type Status struct {
-	Stability            StabilityMap `mapstructure:"stability"`
-	Distributions        []string     `mapstructure:"distributions"`
-	Class                string       `mapstructure:"class"`
-	Warnings             []string     `mapstructure:"warnings"`
-	Codeowners           *Codeowners  `mapstructure:"codeowners"`
-	UnsupportedPlatforms []string     `mapstructure:"unsupported_platforms"`
+	Stability            StabilityMap   `mapstructure:"stability"`
+	Distributions        []string       `mapstructure:"distributions"`
+	Class                string         `mapstructure:"class"`
+	Warnings             []string       `mapstructure:"warnings"`
+	Codeowners           *Codeowners    `mapstructure:"codeowners"`
+	UnsupportedPlatforms []string       `mapstructure:"unsupported_platforms"`
+	Deprecation          DeprecationMap `mapstructure:"deprecation"`
 }
 
 func (s *Status) SortedDistributions() []string {
@@ -80,6 +82,9 @@ func (s *Status) Validate() error {
 	if err := s.Stability.Validate(); err != nil {
 		errs = errors.Join(errs, err)
 	}
+	if err := s.Deprecation.Validate(s.Stability); err != nil {
+		errs = errors.Join(errs, err)
+	}
 	return errs
 }
 
@@ -135,3 +140,38 @@ func (ms StabilityMap) Validate() error {
 	}
 	return errs
 }
+
+type DeprecationMap map[string]DeprecationInfo
+
+type DeprecationInfo struct {
+	Date      string `mapstructure:"date"`
+	Migration string `mapstructure:"migration"`
+}
+
+func (dm DeprecationMap) Validate(ms StabilityMap) error {
+	var errs error
+	for stability, cmps := range ms {
+		if stability != component.StabilityLevelDeprecated {
+			continue
+		}
+		for _, c := range cmps {
+			depInfo, found := dm[c]
+			if !found {
+				errs = errors.Join(errs, fmt.Errorf("deprecated component missing date and migration guide: %v", c))
+				continue
+			}
+			if depInfo.Migration == "" {
+				errs = errors.Join(errs, fmt.Errorf("deprecated component missing migration guide: %v", c))
+			}
+			if depInfo.Date == "" {
+				errs = errors.Join(errs, fmt.Errorf("deprecated component missing date in YYYY-MM-DD format: %v", c))
+			} else {
+				_, err := time.Parse("2006-01-02", depInfo.Date)
+				if err != nil {
+					errs = errors.Join(errs, fmt.Errorf("deprecated component missing valid date in YYYY-MM-DD format: %v", c))
+				}
+			}
+		}
+	}
+	return errs
+}

cmd/mdatagen/internal/templates/readme.md.tmpl

@@ -10,6 +10,12 @@
 | {{ if not $idx }}Stability{{ else }}         {{ end }}     | [{{ toLowerCase $stability.String }}]{{ if ne $class "extension" }}: {{ stringsJoin $value ", " }} {{ end }}  |
 {{- $idx = inc $idx }}
 {{- end }}
+{{- if .Status.Deprecation }}
+{{- range $deprecation, $value := .Status.Deprecation }}
+| Deprecation of {{ toLowerCase $deprecation }} | [Date]: {{ $value.Date }}{{ if ne $class "extension" }} {{ end }}  |
+|                      | [Migration Note]: {{ $value.Migration }}{{ if ne $class "extension" }} {{ end }}  |
+{{- end }}
+{{- end }}
 {{- end}}
 {{- if .Status.UnsupportedPlatforms }}
 | Unsupported Platforms | {{ stringsJoin .Status.UnsupportedPlatforms ", " }} |
@@ -34,6 +40,10 @@
 {{range $stability, $val := .Status.Stability}}
 [{{ toLowerCase $stability.String }}]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#{{ toLowerCase $stability.String }}
 {{- end }}
+{{- if .Status.Deprecation }}
+[Date]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
+[Migration Note]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
+{{- end }}
 {{- range .Status.SortedDistributions }}
 [{{.}}]: {{ distroURL . }}
 {{- end }}

cmd/mdatagen/internal/testdata/deprecation_info_invalid_date.yaml

@@ -0,0 +1,11 @@
+type: file
+status:
+  class: receiver
+  stability:
+    beta: [logs]
+    stable: [metrics]
+    deprecated: [traces]
+  deprecation:
+    traces:
+      date: "05-09-2007"
+      migration: "no migration needed"

cmd/mdatagen/internal/testdata/no_deprecation_date_info.yaml

@@ -0,0 +1,10 @@
+type: file
+status:
+  class: receiver
+  stability:
+    beta: [logs]
+    stable: [metrics]
+    deprecated: [traces]
+  deprecation:
+    traces:
+      migration: "no migration needed"

cmd/mdatagen/internal/testdata/no_deprecation_info.yaml

@@ -0,0 +1,7 @@
+type: file
+status:
+  class: receiver
+  stability:
+    beta: [logs]
+    stable: [metrics]
+    deprecated: [traces]

cmd/mdatagen/internal/testdata/no_deprecation_migration_info.yaml

@@ -0,0 +1,10 @@
+type: file
+status:
+  class: receiver
+  stability:
+    beta: [logs]
+    stable: [metrics]
+    deprecated: [traces]
+  deprecation:
+    traces:
+      date: "2006-05-09"

cmd/mdatagen/internal/testdata/readme_with_multiple_signals_and_deprecation.md

@@ -0,0 +1,21 @@
+# Some component
+
+<!-- status autogenerated section -->
+| Status        |           |
+| ------------- |-----------|
+| Stability     | [deprecated]: traces   |
+|               | [alpha]: logs   |
+|               | [beta]: metrics   |
+| Deprecation of traces | [Date]: 2025-02-05   |
+|                      | [Migration Note]: no migration needed   |
+| Distributions | [contrib] |
+
+[deprecated]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecated
+[alpha]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#alpha
+[beta]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#beta
+[Date]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
+[Migration Note]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
+[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
+<!-- end autogenerated section -->
+
+Some info about a component

cmd/mdatagen/metadata-schema.yaml

@@ -22,6 +22,11 @@ status:
     stable: [<metrics|traces|logs|traces_to_metrics|metrics_to_metrics|logs_to_metrics|extension>]
     deprecated: [<metrics|traces|logs|traces_to_metrics|metrics_to_metrics|logs_to_metrics|extension>]
     unmaintained: [<metrics|traces|logs|traces_to_metrics|metrics_to_metrics|logs_to_metrics|extension>]
+  # Required for deprecated components: The deprecation information for the components - See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#deprecation-information
+  deprecation:
+    <component>:
+      date: string
+      migration: string
   # Optional: The distributions that this component is bundled with (For example core or contrib). See statusdata.go for a list of common distros.
   distributions: [string]
   # Optional: A list of warnings that should be brought to the attention of users looking to use this component

docs/component-stability.md

@@ -257,6 +257,12 @@ To move within the 'Maintained' ladder ("graduate"), the process for doing so is
 3. If approved, a PR to change the stability level should be opened and MUST be approved by all
    listed code owners.
 
+## Deprecation Information
+
+When a component is moved to deprecated, a deprecation section should indicate the date it was deprecated
+as well as any migration guidance. In some occasions it might not offered migration guidance but reviewers should
+explicitely agree on this, and use a "No migration is offered for this component" hint.
+
 ## Versioning
 
 For a component to be marked as 1.x it MUST be stable for at least one signal.