diff --git a/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs b/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs index fd57b1615..4c5d777f6 100644 --- a/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs +++ b/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs @@ -11,35 +11,35 @@ public class ChangelogConfiguration { public List 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 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 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? AvailableAreas { get; set; } diff --git a/src/services/Elastic.Documentation.Services/ChangelogService.cs b/src/services/Elastic.Documentation.Services/ChangelogService.cs index bf713c943..36325e3c6 100644 --- a/src/services/Elastic.Documentation.Services/ChangelogService.cs +++ b/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} """;