Edit comments in changelog file (#2337)

Author: lcawl

src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs

@@ -11,35 +11,35 @@ public class ChangelogConfiguration
 {
 	public List<string> AvailableTypes { get; set; } =
 	[
-		"feature",
-		"enhancement",
-		"bug-fix",
-		"known-issue",
-		"breaking-change",
-		"deprecation",
-		"docs",
-		"regression",
-		"security",
-		"other"
+		"feature", // A new feature or enhancement.
+		"enhancement", // An improvement to an existing feature.
+		"bug-fix", // A bug fix.
+		"known-issue", // A problem that is known to exist in the product.
+		"breaking-change", // A breaking change to the documented behavior of the product.
+		"deprecation", // Functionality that is deprecated and will be removed in a future release.
+		"docs", // Major documentation changes or reorganizations.
+		"regression", // Functionality that no longer works or behaves incorrectly.
+		"security", // An advisory about a potentialsecurity vulnerability.
+		"other" // Changes that do not fit into any of the other categories.
 	];
 
 	public List<string> AvailableSubtypes { get; set; } =
 	[
-		"api",
-		"behavioral",
-		"configuration",
-		"dependency",
-		"subscription",
-		"plugin",
-		"security",
-		"other"
+		"api", // A change that breaks an API.
+		"behavioral", // A change that breaks the way something works.
+		"configuration", // A change that breaks the configuration.
+		"dependency", // A change that breaks a dependency, such as a third-party product.
+		"subscription", // A change that breaks licensing behavior.
+		"plugin", // A change that breaks a plugin.
+		"security", // A change that breaks authentication, authorization, or permissions.
+		"other" // A breaking change that do not fit into any of the other categories.
 	];
 
 	public List<string> AvailableLifecycles { get; set; } =
 	[
-		"preview",
-		"beta",
-		"ga"
+		"preview", // A technical preview of a feature or enhancement.
+		"beta", // A beta release of a feature or enhancement.
+		"ga", // A generally available release of a feature or enhancement.
 	];
 
 	public List<string>? AvailableAreas { get; set; }

src/services/Elastic.Documentation.Services/ChangelogService.cs

@@ -234,39 +234,77 @@ private string GenerateYaml(ChangelogData data, ChangelogConfiguration config)
 		var typesList = string.Join("\n", config.AvailableTypes.Select(t => $"#   - {t}"));
 
 		// Build subtypes list
-		var subtypesList = config.AvailableSubtypes.Count > 0
-			? "\n#   It can be one of:\n" + string.Join("\n", config.AvailableSubtypes.Select(s => $"#   - {s}"))
-			: string.Empty;
+		var subtypesList = string.Join("\n", config.AvailableSubtypes.Select(s => $"#   - {s}"));
+
+		// Build lifecycles list
+		var lifecyclesList = string.Join("\n", config.AvailableLifecycles.Select(l => $"#       - {l}"));
 
 		// Add schema comments using raw string literal
 		var result = $"""
-			##### Automated fields #####
+			##### Required fields #####
 
-			# These fields are likely generated when the changelog is created and unlikely to require edits
+			# title:
+			#   A required string that is a short, user-facing headline.
+			#   (Max 80 characters)
 
-			# pr: An optional string that contains the pull request number
-			# issues: An optional array of strings that contain URLs for issues that are relevant to the PR
-			# type: A required string that contains the type of change
+			# type:
+			#   A required string that contains the type of change
 			#   It can be one of:
 			{typesList}
-			# subtype: An optional string that applies only to breaking changes{subtypesList}
-			# products: A required array of objects that denote the affected products
-			#   Each product object contains:
-			#     - product: A required string with a predefined product ID
-			#     - target: An optional string with the target version or date
-			#     - lifecycle: An optional string (preview, beta, ga)
-			# areas: An optional array of strings that denotes the parts/components/services affected
-
-			##### Non-automated fields #####
 
-			# These fields might be generated when the changelog is created but are likely to require edits
-
-			# title: A required string that is a short, user-facing headline (Max 80 characters)
-			# description: An optional string that provides additional information (Max 600 characters)
-			# impact: An optional string that describes how the user's environment is affected
-			# action: An optional string that describes what users must do to mitigate
-			# feature-id: An optional string to associate with a unique feature flag
-			# highlight: An optional boolean for items that should be included in release highlights
+			# products:
+			#   A required array of objects that denote the affected products
+			#   Each product object contains:
+			#
+			#   - product:
+			#       A required string with a valid product ID.
+			#       Valid values are defined in https://github.com/elastic/docs-builder/blob/main/config/products.yml
+			#
+			#     target:
+			#       An optional string with the target version or date.
+			#
+			#     lifecycle:
+			#       An optional string for new features or enhancements that have a specific availability.
+			#       It can be one of:
+			{lifecyclesList}
+			
+			##### Optional fields #####
+
+			# action:
+			#   An optional string that describes what users must do to mitigate
+			#   the impact of a breaking change or known issue.
+
+			# areas:
+			#   An optional array of strings that denotes the parts/components/services
+			#   of the product that are affected.
+
+			# description:
+			#   An optional string that provides additional information.
+			#   (Max 600 characters).
+
+			# feature-id:
+			#   An optional string to associate a feature or enhanceent with a
+			#   unique feature flag.
+
+			# highlight:
+			#   An optional boolean for items that should be included in release
+			#   highlights or the UI to draw user attention.
+
+			# impact:
+			#   An optional string that describes how the user's environment is
+			#   affected by a breaking change or known issue.
+
+			# issues:
+			#   An optional array of strings that contain the issues that are
+			#   relevant to the PR.
+
+			# pr:
+			#   An optional string that contains the pull request number.
+
+			# subtype:
+			#   An optional string that applies only to breaking changes.
+			#   It can be one of:
+			{subtypesList}
 
 			{yaml}
 			""";