Add changelog entries
The docs-builder changelog add command creates a new changelog file from command-line input.
By adding a file for each notable change, you can ultimately generate release documention with a consistent layout for all your products.
This command is associated with an ongoing release docs initiative. Additional workflows are still to come for managing the list of changelogs in each release.
The command generates a YAML file that uses the following schema:
Changelog schema
##### 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: new functionality
# - enhancement: extends functionality but does not break or fix existing behavior
# - bug-fix: fixes a problem in a previous version
# - known-issue: problems that we are aware of in a given version
# - breaking-change: a change to previously-documented behavior
# - deprecation: functionality that is being removed in a later release
# - docs: major documentation updates or reorgs
# - regression: functionality that no longer works or behaves incorrectly
# - security: an advisory about potential security vulnerabilities
# - other: does not fit into any of the other categories
products:
# A required array of objects that denote the affected products and their target release.
- product:
# A required string with a predefined product ID used for release note routing,
# filters, and categorization.
target:
# An optional string that facilitates pre-release doc previews.
# For products with version releases, it contains the target version number (V.R.M).
# For products with date releases, it contains the target release date
# or the date the PR was merged.
lifecycle:
# An optional string for new features and enhancements that have a specific availability.
# It can be one of the following:
# - 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 specifically affected.
# The list of valid values will vary by product.
# The docs for each release typically group the changes by type then by area.
description:
# An optional string that provides additional information about what has changed.
# Max 600 characters
feature-id:
# An optional string to associate a feature or enhancement with a unique feature flag
highlight:
# An optional boolean for items that should be included in release highlights
# or the UI to draw users' attention.
impact:
# An optional string that describes how the user's environment is/will be
# affected by a breaking change.
issues:
# An optional array of strings that contain URLs for issues that are relevant to the PR.
# They are externalized in the release docs so users can follow the links and
# understand the context.
pr:
# An optional string that contains the pull request identifier.
# It is externalized in the release docs so users can follow the link and find more details.
subtype:
# An optional string that applies only to breaking changes and further subdivides that type.
# It can be one of:
# - api: refers to changes that break an api
# - behavioral: refers to changes the way something works
# - configuration: refers to changes that break the configuration
# - dependency: refers to changes like removing support for third-party products
# - subscription: refers to changes that break licensing behavior
# - plugin: refers to changes that break a plugin
# - security: refers to changes that break authentication, authorization, or permissions
# - other: does not fit into any of the other categories
The command supports all of the following options, which generally align with fields in the changelog schema:
Usage: changelog add [options...] [-h|--help] [--version]
Add a new changelog fragment from command-line input
Options:
--title <string> Required: A short, user-facing title (max 80 characters) (Required)
--type <string> Required: Type of change (feature, enhancement, bug-fix, breaking-change, etc.) (Required)
--products <List<ProductInfo>> Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") (Required)
--subtype <string?> Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) (Default: null)
--areas <string[]?> Optional: Area(s) affected (comma-separated or specify multiple times) (Default: null)
--pr <string?> Optional: Pull request URL (Default: null)
--issues <string[]?> Optional: Issue URL(s) (comma-separated or specify multiple times) (Default: null)
--description <string?> Optional: Additional information about the change (max 600 characters) (Default: null)
--impact <string?> Optional: How the user's environment is affected (Default: null)
--action <string?> Optional: What users must do to mitigate (Default: null)
--feature-id <string?> Optional: Feature flag ID (Default: null)
--highlight <bool?> Optional: Include in release highlights (Default: null)
--output <string?> Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null)
--config <string?> Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' (Default: null)
The --products parameter accepts products in the format "product target lifecycle, ..." where:
productis the product ID from products.yml (required)targetis the target version or date (optional)lifecycleis one of:preview,beta, orga(optional)
Examples:
"kibana 9.2.0 ga""cloud-serverless 2025-08-05""cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"
Some of the fields in the changelog accept only a specific set of values.
- Product values must exist in products.yml. Invalid products will cause the command to fail.
- Type, subtype, and lifecycle values must match the available values defined in ChangelogConfiguration.cs. Invalid values will cause the command to fail.
If you want to further limit the list of values, you can optionally create a configuration file. Refer to changelog.yml.example.
By default, the command checks the following path: docs/changelog.yml.
You can specify a different path with the --config command option.
If a configuration file exists, the command validates all its values before generating the changelog file:
- If the configuration file contains
lifecycle,product,subtype, ortypevalues that don't match the values inproducts.ymlandChangelogConfiguration.cs, validation fails. The changelog file is not created. - If the configuration file contains
areasvalues and they don't match what you specify in the--areascommand option, validation fails. The changelog file is not created.
The following command creates a changelog for a bug fix that applies to two products:
docs-builder changelog add \
--title "Fixes enrich and lookup join resolution based on minimum transport version" \
--type bug-fix \
--products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \
--areas "ES|QL"
--pr "https://github.com/elastic/elasticsearch/pull/137431"
- The type values are defined in ChangelogConfiguration.cs.
- The product values are defined in products.yml.
- At this time, the PR value can be a number or a URL; it is not validated.
The output file has the following format:
pr: https://github.com/elastic/elasticsearch/pull/137431
type: bug-fix
products:
- product: elasticsearch
target: 9.2.3
- product: cloud-serverless
target: 2025-12-02
title: Fixes enrich and lookup join resolution based on minimum transport version
areas:
- ES|QL