﻿---
title: Create changelogs
description: By adding a changelog file for each notable change, you can ultimately generate release documention with a consistent layout for all your products. These...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2472/contribute/changelog
---

# Create changelogs
By adding a changelog file for each notable change, you can ultimately generate release documention with a consistent layout for all your products.
These instructions rely on the use of a common changelog schema:
<dropdown title="Changelog schema">
  ```yaml
  ##### 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.
  # Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values.

  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.
        # Refer to https://github.com/elastic/docs-builder/blob/main/config/products.yml for the acceptable values.

        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.
        # Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values.

  ##### 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.
  # Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values.
  ```
</dropdown>

Some of the fields in the schema accept only a specific set of values:
<important>
  - Product values must exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). Invalid products will cause the `docs-builder changelog add` command to fail.
  - Type, subtype, and lifecycle values must match the available values defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). Invalid values will cause the `docs-builder changelog add` command to fail.
</important>

To use the `docs-builder changelog` commands in your development workflow:
1. Ensure that your products exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
2. Add labels to your GitHub pull requests to represent the types defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). For example, `>bug` and `>enhancement` labels.
3. Optional: Choose areas or components that your changes affect and add labels to your GitHub pull requests (such as `:Analytics/Aggregations`).
4. Optional: Add labels to your GitHub pull requests to indicate that they are not notable and should not generate changelogs. For example, `non-issue` or `release_notes:skip`.
5. [Configure changelog settings](#changelog-settings) to correctly interpret your PR labels.
6. [Create changelogs](#changelog-add) with the `docs-builder changelog add` command.

For more information about running `docs-builder`, go to [Contribute locally](https://www.elastic.co/docs/contribute-docs/locally).
<note>
  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.
</note>


## Create a changelog configuration file

You can create a configuration file to limit the acceptable product, type, subtype, and lifecycle values.
You can also use it to prevent the creation of changelogs when certain PR labels are present.
Refer to [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example).
By default, the `docs-builder changelog add` 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 its values before generating changelog files:
- If the configuration file contains `lifecycle`, `product`, `subtype`, or `type` values that don't match the values in `products.yml` and `ChangelogConfiguration.cs`, validation fails. The changelog file is not created.
- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails. The changelog file is not created.


### GitHub label mappings

You can optionally add `label_to_type` and `label_to_areas` mappings in your changelog configuration.
When you run the `docs-builder changelog add` command with the `--prs` option, it can use these mappings to fill in the `type` and `areas` in your changelog based on your pull request labels.
Refer to the file layout in [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example) and an [example usage](#example-map-label).

### GitHub label blockers

You can also optionally use `add_blockers` in your changelog configuration.
When you run the `docs-builder changelog add` command with the `--prs` and `--products` options and the PR has a label that you've identified as a blocker for that product, the command does not create a changelog for that PR.
You can use comma-separated product IDs to share the same list of labels across multiple products.
Refer to the file layout in [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example) and an [example usage](#example-block-label).

## Create changelog files

You can use the `docs-builder changelog add` command to create a changelog file.
For up-to-date details, use the `-h` option:
```sh
Add a new changelog from command-line input

Options:
  --products <List<ProductInfo>>    Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") [Required]
  --title <string?>                 Optional: A short, user-facing title (max 80 characters). Required if --prs is not specified. If --prs and --title are specified, the latter value is used instead of what exists in the PR. [Default: null]
  --type <string?>                  Optional: Type of change (feature, enhancement, bug-fix, breaking-change, etc.). Required if --prs is not specified. If mappings are configured, type can be derived from the PR. [Default: null]
  --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]
  --prs <string[]?>                 Optional: Pull request URL(s) or PR number(s) (comma-separated, or if --owner and --repo are provided, just numbers). If specified, --title can be derived from the PR. If mappings are configured, --areas and --type can also be derived from the PR. Creates one changelog file per PR. [Default: null]
  --owner <string?>                 Optional: GitHub repository owner (used when --prs contains just numbers) [Default: null]
  --repo <string?>                  Optional: GitHub repository name (used when --prs contains just numbers) [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]
  --use-pr-number                   Optional: Use the PR number as the filename instead of generating it from a unique ID and title
```


### Product format

The `--products` parameter accepts products in the format `"product target lifecycle, ..."` where:
- `product` is the product ID from [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required)
- `target` is the target version or date (optional)
- `lifecycle` is one of: `preview`, `beta`, or `ga` (optional)

Examples:
- `"kibana 9.2.0 ga"`
- `"cloud-serverless 2025-08-05"`
- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"`


### Filenames

By default, the `docs-builder changelog add` command generates filenames using a timestamp and a sanitized version of the title:
`{timestamp}-{sanitized-title}.yaml`
For example: `1735689600-fixes-enrich-and-lookup-join-resolution.yaml`
If you want to use the PR number as the filename instead, add the `--use-pr-number` option:
```sh
docs-builder changelog add \
  --pr https://github.com/elastic/elasticsearch/pull/137431 \
  --products "elasticsearch 9.2.3" \
  --use-pr-number
```

This creates a file named `137431.yaml` instead of the default timestamp-based filename.
<important>
  When using `--use-pr-number`, you must also provide the `--pr` option. The PR number is extracted from the PR URL or number you provide.
</important>


## Examples


### Create a changelog for multiple products

The following command creates a changelog for a bug fix that applies to two products:
```sh
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"
  --prs "https://github.com/elastic/elasticsearch/pull/137431" 
```

The output file has the following format:
```yaml
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
```


### Create a changelog with PR label mappings

You can update your changelog configuration file to contain GitHub label mappings, for example:
```yaml
# Available areas (optional - if not specified, all areas are allowed)
available_areas:
  - search
  - security
  - machine-learning
  - observability
  - index-management
  - ES|QL
  # Add more areas as needed

# GitHub label mappings (optional - used when --prs option is specified)
# Maps GitHub PR labels to changelog type values
# When a PR has a label that matches a key, the corresponding type value is used
label_to_type:
  # Example mappings - customize based on your label naming conventions
  ">enhancement": enhancement
  ">breaking": breaking-change

# Maps GitHub PR labels to changelog area values
# Multiple labels can map to the same area, and a single label can map to multiple areas (comma-separated)
label_to_areas:
  # Example mappings - customize based on your label naming conventions
  ":Search Relevance/ES|QL": "ES|QL"
```

When you use the `--prs` option to derive information from a pull request, it can make use of those mappings:
```sh
docs-builder changelog add \
  --prs https://github.com/elastic/elasticsearch/pull/139272 \
  --products "elasticsearch 9.3.0" \
  --config test/changelog.yml
```

In this case, the changelog file derives the title, type, and areas from the pull request:
```yaml
pr: https://github.com/elastic/elasticsearch/pull/139272
type: enhancement
products:
- product: elasticsearch
  target: 9.3.0
areas:
- ES|QL
title: '[ES|QL] Take TOP_SNIPPETS out of snapshot'
```


### Block changelog creation with PR labels

You can configure product-specific label blockers to prevent changelog creation for certain PRs based on their labels.
If you run the `docs-builder changelog add` command with the `--prs` option and a PR has a blocking label for any of the products in the `--products` option, that PR will be skipped and no changelog file will be created for it.
A warning message will be emitted indicating which PR was skipped and why.
For example, your configuration file can contain `add_blockers` like this:
```yaml
# Product-specific label blockers (optional)
# Maps product IDs to lists of labels that prevent changelog creation for that product
# If you run the changelog add command with the --prs option and a PR has any of these labels, the changelog is not created
# Product IDs can be comma-separated to share the same list of labels across multiple products
add_blockers:
  # Example: Skip changelog for cloud.serverless product when PR has "Watcher" label
  cloud-serverless:
    - ":Data Management/Watcher"
    - ">non-issue"
  # Example: Skip changelog creation for elasticsearch product when PR has "skip:releaseNotes" label
  elasticsearch:
    - ">non-issue"
  # Example: Share the same blockers across multiple products using comma-separated product IDs
  elasticsearch, cloud-serverless:
    - ">non-issue"
```

Those settings affect commands with the `--prs` option, for example:
```sh
docs-builder changelog add --prs "1234, 5678" \
  --products "cloud-serverless" \
  --owner elastic --repo elasticsearch \
  --config test/changelog.yml
```

If PR 1234 has the `>non-issue` or Watcher label, it will be skipped and no changelog will be created for it.
If PR 5678 does not have any blocking labels, a changelog is created.

### Create changelogs from a file of PRs

You can also provide PRs from a file containing newline-delimited PR URLs or numbers:
```sh
# Create a file with PRs (one per line)
cat > prs.txt << EOF
https://github.com/elastic/elasticsearch/pull/1234
https://github.com/elastic/elasticsearch/pull/5678
EOF

# Use the file with --prs
docs-builder changelog add --prs prs.txt \
  --products "elasticsearch 9.2.0 ga" \
  --config test/changelog.yml
```

You can also mix file paths and comma-separated PRs:
```sh
docs-builder changelog add \
  --prs "https://github.com/elastic/elasticsearch/pull/1234" \
  --prs prs.txt \
  --prs "5678, 9012" \
  --products "elasticsearch 9.2.0 ga" \
  --owner elastic --repo elasticsearch \
  --config test/changelog.yml
```

This creates one changelog file for each PR specified, whether from files or directly.