diff --git a/.chloggen/add-display-name-14114.yaml b/.chloggen/add-display-name-14114.yaml new file mode 100644 index 00000000000..92c34b25a9b --- /dev/null +++ b/.chloggen/add-display-name-14114.yaml @@ -0,0 +1,28 @@ +# 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: cmd/mdatagen + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add optional `display_name` and `description` fields to metadata.yaml for human-readable component names + +# One or more tracking issues or pull requests related to the change +issues: [14114] + +# (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: | + The `display_name` field allows components to specify a human-readable name in metadata.yaml. + When provided, this name is used as the title in generated README files. + The `description` field allows components to include a brief description in generated README files. + +# 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: [user] diff --git a/.github/workflows/utils/cspell.json b/.github/workflows/utils/cspell.json index dcec12199e6..f999b772c1b 100644 --- a/.github/workflows/utils/cspell.json +++ b/.github/workflows/utils/cspell.json @@ -321,6 +321,7 @@ "myreceiver", "myrepo", "mysite", + "nodisplayname", "nonclobbering", "nopexporter", "nopreceiver", @@ -457,6 +458,7 @@ "testcomponents", "testconverter", "testdata", + "testdesc", "testfunc", "testonly", "testprocessor", diff --git a/cmd/mdatagen/internal/loader_test.go b/cmd/mdatagen/internal/loader_test.go index 5a144aacaec..3911853e5a8 100644 --- a/cmd/mdatagen/internal/loader_test.go +++ b/cmd/mdatagen/internal/loader_test.go @@ -47,6 +47,8 @@ func TestLoadMetadata(t *testing.T) { GithubProject: "open-telemetry/opentelemetry-collector", GeneratedPackageName: "metadata", Type: "sample", + DisplayName: "Sample Receiver", + Description: "This receiver is used for testing purposes to check the output of mdatagen.", SemConvVersion: "1.38.0", PackageName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/samplereceiver", Status: &Status{ @@ -553,6 +555,61 @@ func TestLoadMetadata(t *testing.T) { name: "testdata/~~this file doesn't exist~~.yaml", wantErr: "unable to read the file file:testdata/~~this file doesn't exist~~.yaml", }, + { + name: "testdata/display_name.yaml", + want: Metadata{ + Type: "test", + DisplayName: "Test Receiver", + GeneratedPackageName: "metadata", + ScopeName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata", + PackageName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata", + ShortFolderName: "testdata", + Tests: Tests{Host: "newMdatagenNopHost()"}, + Status: &Status{ + Class: "receiver", + Stability: map[component.StabilityLevel][]string{ + component.StabilityLevelBeta: {"logs"}, + }, + }, + }, + }, + { + name: "testdata/no_display_name.yaml", + want: Metadata{ + Type: "nodisplayname", + DisplayName: "", + GeneratedPackageName: "metadata", + ScopeName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata", + PackageName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata", + ShortFolderName: "testdata", + Tests: Tests{Host: "newMdatagenNopHost()"}, + Status: &Status{ + Class: "receiver", + Stability: map[component.StabilityLevel][]string{ + component.StabilityLevelBeta: {"logs"}, + }, + }, + }, + }, + { + name: "testdata/with_description.yaml", + want: Metadata{ + Type: "testdesc", + DisplayName: "Test Component", + Description: "This is a test component with a description.", + GeneratedPackageName: "metadata", + ScopeName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata", + PackageName: "go.opentelemetry.io/collector/cmd/mdatagen/internal/testdata", + ShortFolderName: "testdata", + Tests: Tests{Host: "newMdatagenNopHost()"}, + Status: &Status{ + Class: "receiver", + Stability: map[component.StabilityLevel][]string{ + component.StabilityLevelBeta: {"logs"}, + }, + }, + }, + }, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { diff --git a/cmd/mdatagen/internal/metadata.go b/cmd/mdatagen/internal/metadata.go index d5355273e72..4a8ae82b37a 100644 --- a/cmd/mdatagen/internal/metadata.go +++ b/cmd/mdatagen/internal/metadata.go @@ -18,6 +18,10 @@ import ( type Metadata struct { // Type of the component. Type string `mapstructure:"type"` + // DisplayName is a human-readable display name for the component. + DisplayName string `mapstructure:"display_name"` + // Description is a brief description of the component. + Description string `mapstructure:"description"` // Type of the parent component (applicable to subcomponents). Parent string `mapstructure:"parent"` // Status information for the component. diff --git a/cmd/mdatagen/internal/sampleconnector/metadata.yaml b/cmd/mdatagen/internal/sampleconnector/metadata.yaml index 99c25baa499..65479d20430 100644 --- a/cmd/mdatagen/internal/sampleconnector/metadata.yaml +++ b/cmd/mdatagen/internal/sampleconnector/metadata.yaml @@ -1,6 +1,8 @@ # Sample metadata file with all available configurations for a connector. type: sample +display_name: Sample Connector +description: This connector is used for testing purposes to check the output of mdatagen. github_project: open-telemetry/opentelemetry-collector sem_conv_version: 1.9.0 diff --git a/cmd/mdatagen/internal/samplefactoryreceiver/README.md b/cmd/mdatagen/internal/samplefactoryreceiver/README.md index 6a12429d7cf..349ad9f4449 100644 --- a/cmd/mdatagen/internal/samplefactoryreceiver/README.md +++ b/cmd/mdatagen/internal/samplefactoryreceiver/README.md @@ -1,6 +1,8 @@ -# Sample Receiver -This receiver is used for testing purposes to check the output of mdatagen. +# Sample Factory Receiver + +This receiver is used for testing purposes to check the output of mdatagen. + | Status | | | ------------- |-----------| | Stability | [deprecated]: profiles | diff --git a/cmd/mdatagen/internal/samplefactoryreceiver/metadata.yaml b/cmd/mdatagen/internal/samplefactoryreceiver/metadata.yaml index a64cd97fd72..7c8679e679b 100644 --- a/cmd/mdatagen/internal/samplefactoryreceiver/metadata.yaml +++ b/cmd/mdatagen/internal/samplefactoryreceiver/metadata.yaml @@ -1,6 +1,8 @@ # Sample metadata file with all available configurations for a receiver. type: sample +display_name: Sample Factory Receiver +description: This receiver is used for testing purposes to check the output of mdatagen. scope_name: go.opentelemetry.io/collector/internal/receiver/samplefactoryreceiver github_project: open-telemetry/opentelemetry-collector diff --git a/cmd/mdatagen/internal/sampleprocessor/README.md b/cmd/mdatagen/internal/sampleprocessor/README.md index 48c23b1e51b..586cb5874f5 100644 --- a/cmd/mdatagen/internal/sampleprocessor/README.md +++ b/cmd/mdatagen/internal/sampleprocessor/README.md @@ -1,6 +1,8 @@ + # Sample Processor + This processor is used for testing purposes to check the output of mdatagen. - + | Status | | | ------------- |-----------| | Stability | [development]: logs | diff --git a/cmd/mdatagen/internal/sampleprocessor/metadata.yaml b/cmd/mdatagen/internal/sampleprocessor/metadata.yaml index ce7f738c0f6..e69f5fcbf1f 100644 --- a/cmd/mdatagen/internal/sampleprocessor/metadata.yaml +++ b/cmd/mdatagen/internal/sampleprocessor/metadata.yaml @@ -1,6 +1,8 @@ -# Sample metadata file with all available configurations for a receiver. +# Sample metadata file with all available configurations for a processor. type: sample +display_name: Sample Processor +description: This processor is used for testing purposes to check the output of mdatagen. scope_name: go.opentelemetry.io/collector/internal/receiver/samplereceiver github_project: open-telemetry/opentelemetry-collector diff --git a/cmd/mdatagen/internal/samplereceiver/README.md b/cmd/mdatagen/internal/samplereceiver/README.md index 70549c2036d..fc299a43fb7 100644 --- a/cmd/mdatagen/internal/samplereceiver/README.md +++ b/cmd/mdatagen/internal/samplereceiver/README.md @@ -1,6 +1,8 @@ + # Sample Receiver + This receiver is used for testing purposes to check the output of mdatagen. - + | Status | | | ------------- |-----------| | Stability | [deprecated]: profiles | diff --git a/cmd/mdatagen/internal/samplereceiver/metadata.yaml b/cmd/mdatagen/internal/samplereceiver/metadata.yaml index e9e05a3768d..e2686676e7f 100644 --- a/cmd/mdatagen/internal/samplereceiver/metadata.yaml +++ b/cmd/mdatagen/internal/samplereceiver/metadata.yaml @@ -1,6 +1,8 @@ # Sample metadata file with all available configurations for a receiver. type: sample +display_name: Sample Receiver +description: This receiver is used for testing purposes to check the output of mdatagen. scope_name: go.opentelemetry.io/collector/internal/receiver/samplereceiver github_project: open-telemetry/opentelemetry-collector diff --git a/cmd/mdatagen/internal/samplescraper/README.md b/cmd/mdatagen/internal/samplescraper/README.md index 5654b3aeb54..ed39d7fb168 100644 --- a/cmd/mdatagen/internal/samplescraper/README.md +++ b/cmd/mdatagen/internal/samplescraper/README.md @@ -1,6 +1,8 @@ + # Sample Scraper + This scraper is used for testing purposes to check the output of mdatagen. - + | Status | | | ------------- |-----------| | Stability | [development]: logs | diff --git a/cmd/mdatagen/internal/samplescraper/metadata.yaml b/cmd/mdatagen/internal/samplescraper/metadata.yaml index eca7f899a83..5ba5f832577 100644 --- a/cmd/mdatagen/internal/samplescraper/metadata.yaml +++ b/cmd/mdatagen/internal/samplescraper/metadata.yaml @@ -1,6 +1,8 @@ # Sample metadata file with all available configurations for a scraper. type: sample +display_name: Sample Scraper +description: This scraper is used for testing purposes to check the output of mdatagen. github_project: open-telemetry/opentelemetry-collector sem_conv_version: 1.38.0 diff --git a/cmd/mdatagen/internal/templates/readme.md.tmpl b/cmd/mdatagen/internal/templates/readme.md.tmpl index 74ff711b8d1..bd707b641bc 100644 --- a/cmd/mdatagen/internal/templates/readme.md.tmpl +++ b/cmd/mdatagen/internal/templates/readme.md.tmpl @@ -1,4 +1,11 @@ +{{- if .DisplayName }} +# {{ .DisplayName }} +{{- end }} +{{- if .Description }} + +{{ .Description }} +{{ end -}} {{- if len .Status.Stability }} | Status | | | ------------- |-----------| diff --git a/cmd/mdatagen/internal/testdata/display_name.yaml b/cmd/mdatagen/internal/testdata/display_name.yaml new file mode 100644 index 00000000000..ea5f9088ecf --- /dev/null +++ b/cmd/mdatagen/internal/testdata/display_name.yaml @@ -0,0 +1,7 @@ +type: test +display_name: Test Receiver + +status: + class: receiver + stability: + beta: [logs] diff --git a/cmd/mdatagen/internal/testdata/no_display_name.yaml b/cmd/mdatagen/internal/testdata/no_display_name.yaml new file mode 100644 index 00000000000..0e7f304c2fc --- /dev/null +++ b/cmd/mdatagen/internal/testdata/no_display_name.yaml @@ -0,0 +1,6 @@ +type: nodisplayname + +status: + class: receiver + stability: + beta: [logs] diff --git a/cmd/mdatagen/internal/testdata/with_description.yaml b/cmd/mdatagen/internal/testdata/with_description.yaml new file mode 100644 index 00000000000..7182bc4e9fa --- /dev/null +++ b/cmd/mdatagen/internal/testdata/with_description.yaml @@ -0,0 +1,8 @@ +type: testdesc +display_name: Test Component +description: This is a test component with a description. + +status: + class: receiver + stability: + beta: [logs] diff --git a/cmd/mdatagen/metadata-schema.yaml b/cmd/mdatagen/metadata-schema.yaml index e11880d26b3..8659966fb06 100644 --- a/cmd/mdatagen/metadata-schema.yaml +++ b/cmd/mdatagen/metadata-schema.yaml @@ -1,6 +1,12 @@ # Required: The type of the component - Usually the name. The type and class combined uniquely identify the component (eg. receiver/otlp) or subcomponent (eg. receiver/hostmetricsreceiver/cpu) type: +# Optional: Human-readable display name for the component. Used as the title in generated README files. +display_name: string + +# Optional: Brief description of the component that will be included in the generated README. +description: string + # Required for subcomponents: The type of the parent component. parent: string