Skip to content

Conversation

@lcawl
Copy link
Contributor

@lcawl lcawl commented Dec 10, 2025

Relates to #2320 (comment)

This PR edits the comments that appear in each generated changelog file, including:

  • Grouping them by whether they're required or optional
  • Adding the list of valid lifecycle states
  • Linking to the list of valid product identifiers

Old comments

##### Automated fields #####

# These fields are likely generated when the changelog is created and unlikely to require edits

# 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
#   It can be one of:
#   - feature
#   - enhancement
#   - bug-fix
#   - known-issue
#   - breaking-change
#   - deprecation
#   - docs
#   - regression
#   - security
#   - other
# subtype: An optional string that applies only to breaking changes
#   It can be one of:
#   - api
#   - behavioral
#   - configuration
#   - dependency
#   - subscription
#   - plugin
#   - security
#   - other
# 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

New comments

##### Required fields #####

# title:
#   A required string that is a short, user-facing headline.
#   (Max 80 characters)

# type:
#   A required string that contains the type of change
#   It can be one of:
#   - feature
#   - enhancement
#   - bug-fix
#   - known-issue
#   - breaking-change
#   - deprecation
#   - docs
#   - regression
#   - security
#   - other

# 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:
#       - preview
#       - beta
#       - ga

##### 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:
#   - api
#   - behavioral
#   - configuration
#   - dependency
#   - subscription
#   - plugin
#   - security
#   - other

@lcawl lcawl mentioned this pull request Dec 10, 2025
2 tasks
@lcawl lcawl marked this pull request as ready for review December 10, 2025 00:44
@lcawl lcawl requested a review from a team as a code owner December 10, 2025 00:44
@lcawl lcawl requested a review from Mpdreamz December 10, 2025 00:44
@lcawl lcawl merged commit 4301061 into main Dec 10, 2025
28 checks passed
@lcawl lcawl deleted the changelog-comments branch December 10, 2025 15:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants