Add docs-builder release-notes create command

[lcawl]

This PR adds a docs-builder command that generates a changelog YAML file.

It is derived from the "elastic-agent-changelog-tool new a-changeset-filename" workflow in https://github.com/elastic/elastic-agent-changelog-tool

For example:

./docs-builder changelog add --pr 130027 --title "Fixes prevent duplication of \"invalid index name\" string in the final exception error message"  --type bug-fix --products "elasticsearch 9.2.0 beta, cloud-serverless 2025-11-11 ga" --areas "ES|QL"

That command creates a file named 1764714171-fixes-prevent-duplication-of-invalid-index-name-st.yaml that contains:

pr: 130027
type: bug-fix
products:
- product: elasticsearch
  target: 9.2.0
  lifecycle: beta
- product: cloud-serverless
  target: 2025-11-11
  lifecycle: ga
areas:
- ES|QL
title: Fixes prevent duplication of "invalid index name" string in the final exception error message

Everything is currently specified on the command line, with only three required options (title, type, and product):

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)

Error handing

You can optionally specify a changelog.yml file (in a docs folder, or specify a different path with the --config option). It enables you to override the list of acceptable values in the type, subtype, products, areas, or product lifecycle values. This is useful, for example, if a repo only generates changelogs for a specific subset of products and only has a specific set of areas that ought to appear in changelogs.

If you provide a value that doesn't match the schema, you get an error and the changelog is not created.
For example, if I omit ES|QL from the list of valid areas in the changelog.yml, I get this error:

The following errors and warnings were found in the documentation

Error: Area 'ES|QL' is not in the list of available areas. Available areas: search, security, machine-learning, observability, index-management

Next steps

• If we want to have even fewer required options, we could follow elastic-agent-changelog-tool new and require only a filename (per https://github.com/elastic/elastic-agent-changelog-tool/blob/main/docs/usage.md#adding-a-changelog-fragment). However, we'd want to add validation that the minimal information exists before a changelog is merged.
• Ultimately the command ought to be able to get information from a pull request to fill in parts of the changelog (i.e. for the use case where the command is being run automatically to add a changelog to an open PR).
  That was the intention behind having a label mapping configuration file.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1 agent

[reakaleek]

wow. thank you for the contribution.

[reakaleek]

Another thing that would be nice.. but probably as a follow-up is somehthing like an interactive form.

If you don't provide all the args, the CLI asks you. Similar to (gh cli)

[reakaleek]

I wonder if applies_to could be the base for it.
Not sure if we can align the syntax. (Also applies_to must be extended to also support dates)

I guess we cannot do this now.. but aligning this in the future could be nice.

I definitely see a connection.

[Mpdreamz]

++ I don't think we need to put dates any longer.

Since in our proposal we would discover what serverless release these go out.

[lcawl]

When we were working on the schema, we originally based it on this list of products: https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/frontmatter#products However, there are some missing from that list (e.g. all the individual EDOT collectors and Elasticsearch Clients, which each have their own set of release notes and thus IMO need a unique product identifier).

Note that since this review, I've edited the PR to handle validation better. Now we can have a list of valid values (for things like the type, subtype, products defined globally in the tool, but individual teams can override that in their changelog.yml config file (if only a subset of the products are applicable to their repo, for example, or they want to allow only a specific list of "areas"). I've also changed it such that if there's a list of valid values and the command diverges from that, the changelog is not generated. Probably additional levels of validation are required (e.g. to ensure that teams can't make up new products, types, or subtypes in their config.yml that don't exist globally) but this is at least a start.

[lcawl]

++ I don't think we need to put dates any longer. Since in our proposal we would discover what serverless release these go out.

I've left that item in the schema for now since at the moment we don't have the longer-term solution.

[Mpdreamz]

We should make https://github.com/elastic/docs-builder/blob/main/config/products.yml the sole source of truth for allowed products.

We should discuss if all of them are allowed in applies_to, I would argue yes.

cc @florent-leborgne

[florent-leborgne]

To capture the slack convo:

Florent:

All of what is listed in https://github.com/elastic/docs-builder/blob/main/config/products.yml is not necessarily used in applies_to, some are used exclusively in products or for subs - I don't think it is an issue to extend the list and also use it for release notes. I wouldn't get rid of anything existing if they're still used for some level of search filtering (as part of the products dimension)

Martijn:

Aye we can always denote to not allow a product in applies_to (or elsewhere), for bookkeeping and data integrity/consistency having one list is just nice

All of this to say: all good 👍 👍 :)

[Mpdreamz]

Few changes but overall looks good 😍

It'd be nice if we can follow up with this with an interactive mode like gh pr create.

EDIT: @reakaleek already mentioned that :)

[Mpdreamz]

One note on products.yml but nothing blocking, this is a great first start 👍