refactor(mdatagen): convert feature gates from map to list

- Changed FeatureGates to []FeatureGate with ID field for preserved ordering
- Added duplicate ID validation
- Updated templates to iterate list using .ID
- Added feature_gates section to schema and README
- Updated tests and testdata
- Removed accidentally committed mdatagen binary

Addresses all feedback from @mx-psi on PR open-telemetry#14130

Author: sAchin-680

cmd/mdatagen/README.md

@@ -72,13 +72,13 @@ status:
     beta: [metrics, traces]
 
 feature_gates:
-  mycomponent.newFeature:
+  - id: mycomponent.newFeature
     description: 'Enables new feature functionality that improves performance'
     stage: alpha
     from_version: 'v0.100.0'
     reference_url: 'https://github.com/open-telemetry/opentelemetry-collector/issues/12345'
 
-  mycomponent.stableFeature:
+  - id: mycomponent.stableFeature
     description: 'A feature that has reached stability'
     stage: stable
     from_version: 'v0.90.0'

cmd/mdatagen/internal/metadata.go

@@ -49,7 +49,8 @@ type Metadata struct {
 	// PackageName is the name of the package where the component is defined.
 	PackageName string `mapstructure:"package_name"`
 	// FeatureGates that are managed by the component.
-	FeatureGates map[FeatureGateID]FeatureGate `mapstructure:"feature_gates"`
+	FeatureGates []FeatureGate `mapstructure:"feature_gates"`
+	// FeatureGates that are managed by the component.
 }
 
 func (md Metadata) GetCodeCovComponentID() string {
@@ -278,16 +279,25 @@ func validateEvents(events map[EventName]Event, attributes map[AttributeName]Att
 
 func (md *Metadata) validateFeatureGates() error {
 	var errs error
-	for gateID, gate := range md.FeatureGates {
+	seen := make(map[FeatureGateID]bool)
+
+	for i, gate := range md.FeatureGates {
 		// Validate gate ID is not empty
-		if string(gateID) == "" {
-			errs = errors.Join(errs, errors.New("feature gate ID cannot be empty"))
+		if string(gate.ID) == "" {
+			errs = errors.Join(errs, fmt.Errorf("feature gate at index %d: ID cannot be empty", i))
+			continue
+		}
+
+		// Check for duplicate IDs
+		if seen[gate.ID] {
+			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": duplicate ID`, gate.ID))
 			continue
 		}
+		seen[gate.ID] = true
 
 		// Validate gate has required fields
 		if gate.Description == "" {
-			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": description is required`, gateID))
+			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": description is required`, gate.ID))
 		}
 
 		// Validate stage is one of the allowed values
@@ -298,20 +308,20 @@ func (md *Metadata) validateFeatureGates() error {
 			FeatureGateStageDeprecated: true,
 		}
 		if !validStages[gate.Stage] {
-			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": invalid stage "%v", must be one of: alpha, beta, stable, deprecated`, gateID, gate.Stage))
+			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": invalid stage "%v", must be one of: alpha, beta, stable, deprecated`, gate.ID, gate.Stage))
 		}
 
 		// Validate version formats if provided
 		if gate.FromVersion != "" && !strings.HasPrefix(gate.FromVersion, "v") {
-			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": from_version "%v" must start with 'v'`, gateID, gate.FromVersion))
+			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": from_version "%v" must start with 'v'`, gate.ID, gate.FromVersion))
 		}
 		if gate.ToVersion != "" && !strings.HasPrefix(gate.ToVersion, "v") {
-			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": to_version "%v" must start with 'v'`, gateID, gate.ToVersion))
+			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": to_version "%v" must start with 'v'`, gate.ID, gate.ToVersion))
 		}
 
 		// Validate that stable/deprecated gates should have to_version
 		if (gate.Stage == FeatureGateStageStable || gate.Stage == FeatureGateStageDeprecated) && gate.ToVersion == "" {
-			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": to_version is required for %v stage gates`, gateID, gate.Stage))
+			errs = errors.Join(errs, fmt.Errorf(`feature gate "%v": to_version is required for %v stage gates`, gate.ID, gate.Stage))
 		}
 	}
 	return errs
@@ -577,6 +587,8 @@ const (
 
 // FeatureGate represents a feature gate definition in metadata.
 type FeatureGate struct {
+	// ID is the unique identifier for the feature gate.
+	ID FeatureGateID `mapstructure:"id"`
 	// Description of the feature gate.
 	Description string `mapstructure:"description"`
 	// Stage is the lifecycle stage of the feature gate.

cmd/mdatagen/internal/metadata_test.go

@@ -328,62 +328,61 @@ func TestValidateFeatureGates(t *testing.T) {
 	tests := []struct {
 		name        string
 		featureGate FeatureGate
-		gateID      FeatureGateID
 		wantErr     string
 	}{
 		{
-			name:   "valid alpha gate",
-			gateID: "component.feature",
+			name: "valid alpha gate",
 			featureGate: FeatureGate{
+				ID:           "component.feature",
 				Description:  "Test feature gate",
 				Stage:        FeatureGateStageAlpha,
 				FromVersion:  "v0.100.0",
 				ReferenceURL: "https://example.com",
 			},
 		},
 		{
-			name:   "valid stable gate with to_version",
-			gateID: "component.stable",
+			name: "valid stable gate with to_version",
 			featureGate: FeatureGate{
+				ID:          "component.stable",
 				Description: "Stable feature gate",
 				Stage:       FeatureGateStageStable,
 				FromVersion: "v0.90.0",
 				ToVersion:   "v0.95.0",
 			},
 		},
 		{
-			name:   "empty description",
-			gateID: "component.feature",
+			name: "empty description",
 			featureGate: FeatureGate{
+				ID:          "component.feature",
 				Stage:       FeatureGateStageAlpha,
 				FromVersion: "v0.100.0",
 			},
 			wantErr: `description is required`,
 		},
 		{
-			name:   "invalid stage",
-			gateID: "component.feature",
+			name: "invalid stage",
 			featureGate: FeatureGate{
+				ID:          "component.feature",
 				Description: "Test feature",
 				Stage:       "invalid",
 				FromVersion: "v0.100.0",
 			},
 			wantErr: `invalid stage "invalid"`,
 		},
 		{
-			name:   "from_version without v prefix",
-			gateID: "component.feature",
+			name: "from_version without v prefix",
 			featureGate: FeatureGate{
+				ID:          "component.feature",
 				Description: "Test feature",
 				Stage:       FeatureGateStageAlpha,
 				FromVersion: "0.100.0",
 			},
 			wantErr: `from_version "0.100.0" must start with 'v'`,
 		},
 		{
-			name:   "to_version without v prefix",
-			gateID: "component.feature",
+			name: "to_version without v prefix",
 			featureGate: FeatureGate{
+				ID:          "component.feature",
 				Description: "Test feature",
 				Stage:       FeatureGateStageStable,
 				FromVersion: "v0.90.0",
@@ -392,19 +391,19 @@ func TestValidateFeatureGates(t *testing.T) {
 			wantErr: `to_version "0.95.0" must start with 'v'`,
 		},
 		{
-			name:   "stable gate missing to_version",
-			gateID: "component.feature",
+			name: "stable gate missing to_version",
 			featureGate: FeatureGate{
+				ID:          "component.feature",
 				Description: "Test feature",
 				Stage:       FeatureGateStageStable,
 				FromVersion: "v0.90.0",
 			},
 			wantErr: `to_version is required for stable stage gates`,
 		},
 		{
-			name:   "deprecated gate missing to_version",
-			gateID: "component.feature",
+			name: "deprecated gate missing to_version",
 			featureGate: FeatureGate{
+				ID:          "component.feature",
 				Description: "Test feature",
 				Stage:       FeatureGateStageDeprecated,
 				FromVersion: "v0.90.0",
@@ -416,9 +415,7 @@ func TestValidateFeatureGates(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			md := &Metadata{
-				FeatureGates: map[FeatureGateID]FeatureGate{
-					tt.gateID: tt.featureGate,
-				},
+				FeatureGates: []FeatureGate{tt.featureGate},
 			}
 			err := md.validateFeatureGates()
 			if tt.wantErr != "" {
@@ -433,14 +430,34 @@ func TestValidateFeatureGates(t *testing.T) {
 
 func TestValidateFeatureGatesEmptyID(t *testing.T) {
 	md := &Metadata{
-		FeatureGates: map[FeatureGateID]FeatureGate{
-			"": {
+		FeatureGates: []FeatureGate{
+			{
 				Description: "Test",
 				Stage:       FeatureGateStageAlpha,
 			},
 		},
 	}
 	err := md.validateFeatureGates()
 	require.Error(t, err)
-	assert.ErrorContains(t, err, "feature gate ID cannot be empty")
+	assert.ErrorContains(t, err, "ID cannot be empty")
+}
+
+func TestValidateFeatureGatesDuplicateID(t *testing.T) {
+	md := &Metadata{
+		FeatureGates: []FeatureGate{
+			{
+				ID:          "component.feature",
+				Description: "Test feature",
+				Stage:       FeatureGateStageAlpha,
+			},
+			{
+				ID:          "component.feature",
+				Description: "Duplicate feature",
+				Stage:       FeatureGateStageAlpha,
+			},
+		},
+	}
+	err := md.validateFeatureGates()
+	require.Error(t, err)
+	assert.ErrorContains(t, err, "duplicate ID")
 }

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

@@ -273,8 +273,8 @@ This component has the following feature gates:
 
 | Feature Gate | Stage | Description | From Version | To Version | Reference |
 | ------------ | ----- | ----------- | ------------ | ---------- | --------- |
-{{- range $gateID, $gate := .FeatureGates }}
-| `{{ $gateID }}` | {{ $gate.Stage }} | {{ $gate.Description }} | {{ if $gate.FromVersion }}{{ $gate.FromVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ToVersion }}{{ $gate.ToVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ReferenceURL }}[Link]({{ $gate.ReferenceURL }}){{ else }}N/A{{ end }} |
+{{- range .FeatureGates }}
+| `{{ .ID }}` | {{ .Stage }} | {{ .Description }} | {{ if .FromVersion }}{{ .FromVersion }}{{ else }}N/A{{ end }} | {{ if .ToVersion }}{{ .ToVersion }}{{ else }}N/A{{ end }} | {{ if .ReferenceURL }}[Link]({{ .ReferenceURL }}){{ else }}N/A{{ end }} |
 {{- end }}
 
 For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.

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

@@ -6,8 +6,8 @@ This component has the following feature gates:
 
 | Feature Gate | Stage | Description | From Version | To Version | Reference |
 | ------------ | ----- | ----------- | ------------ | ---------- | --------- |
-{{- range $gateID, $gate := .FeatureGates }}
-| `{{ $gateID }}` | {{ $gate.Stage }} | {{ $gate.Description }} | {{ if $gate.FromVersion }}{{ $gate.FromVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ToVersion }}{{ $gate.ToVersion }}{{ else }}N/A{{ end }} | {{ if $gate.ReferenceURL }}[Link]({{ $gate.ReferenceURL }}){{ else }}N/A{{ end }} |
+{{- range .FeatureGates }}
+| `{{ .ID }}` | {{ .Stage }} | {{ .Description }} | {{ if .FromVersion }}{{ .FromVersion }}{{ else }}N/A{{ end }} | {{ if .ToVersion }}{{ .ToVersion }}{{ else }}N/A{{ end }} | {{ if .ReferenceURL }}[Link]({{ .ReferenceURL }}){{ else }}N/A{{ end }} |
 {{- end }}
 
 For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.

cmd/mdatagen/internal/testdata/documentation.md

@@ -2,13 +2,10 @@
 
 # sample
 
-## Feature Gates
+## Resource Attributes
 
-This component has the following feature gates:
-
-| Feature Gate | Stage | Description | From Version | To Version | Reference |
-| ------------ | ----- | ----------- | ------------ | ---------- | --------- |
-| `sample.feature.gate` | alpha | This is a sample feature gate for testing purposes | v0.100.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector/issues/12345) |
-| `stable.feature.gate` | stable | This is a stable feature gate | v0.90.0 | v0.95.0 | [Link](https://github.com/open-telemetry/opentelemetry-collector/issues/11111) |
-
-For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.
+| Name | Description | Values | Enabled |
+| ---- | ----------- | ------ | ------- |
+| host.id | The unique host identifier | Any Str | true |
+| host.name | The hostname | Any Str | true |
+| process.pid | The process identifier | Any Int | true |

cmd/mdatagen/internal/testdata/feature_gates.yaml

@@ -5,13 +5,13 @@ status:
     beta: [metrics]
 
 feature_gates:
-  sample.feature.gate:
+  - id: sample.feature.gate
     description: 'This is a sample feature gate for testing purposes'
     stage: alpha
     from_version: 'v0.100.0'
     reference_url: 'https://github.com/open-telemetry/opentelemetry-collector/issues/12345'
 
-  stable.feature.gate:
+  - id: stable.feature.gate
     description: 'This is a stable feature gate'
     stage: stable
     from_version: 'v0.90.0'

cmd/mdatagen/mdatagen

@@ -260,9 +260,10 @@ telemetry:
       # Note: Only the following attribute types are supported: <string|int|double|bool>
       attributes: [string]
 
-# Optional: map of feature gate definitions with the key being the gate ID.
+# Optional: list of feature gate definitions.
 feature_gates:
-  <gate.id>:
+  - # Required: unique identifier for the feature gate.
+    id: <gate.id>
     # Required: description of the feature gate.
     description: string
     # Required: lifecycle stage of the feature gate.