[theletterf]

While working out what Elasticsearch still needs for unified release notes, I found that docs-builder can't read the changelog entries Elasticsearch already writes. Rather than teach it that one format in code, this makes entry formats data that a repository opts into.

Why

elastic/elasticsearch keeps one file per PR in docs/changelog/ with pr, summary, area, type and issues, plus optional breaking, deprecation and highlight blocks. docs-builder rejected all 715 of them (Property 'area' not found or Property 'summary' not found). That has two effects today:

• Adding the shared release-notes.yml workflow to Elasticsearch would fail release-notes / validate on every PR that adds an entry, about a quarter of recent PRs.
• The Elasticsearch pool on the CDN already holds 772 files in that format, and commit-range bundling (release unified bundle, release serverless) fails with "matches PR #N but could not be parsed" when a PR in the range has one.

Beats, elastic-agent and fleet-server have the same problem with a third format (elastic-agent-changelog-tool fragments), so a one-off conversion wouldn't last.

What

• Formats are data. config/changelog-entry-formats.yml (embedded) defines each format as a mapping from docs-builder fields to source fields: from (first path with a value wins, nested paths like breaking.details), split, unless, template, present, per-field values translations, and ignore. Any other key in a source file is an error, so typos still surface. It ships two formats:
  • elasticsearch: summary → title, area → areas, bug/breaking/breaking-java/new-aggregation/upgrade → bug-fix/breaking-change/breaking-change/feature/other, block details/impact/body → description/impact, highlight → highlight, source_repo → prs: elastic/<repo>#<pr>.
  • elastic-agent-changelog-tool: kind, summary, description, component, pr, issue, impact, action.
• Repositories opt in. entry_format: <name> in changelog.yml. An unknown name is a configuration error that lists the known ones. Nothing changes for a repository that doesn't set it.
• Conversion happens where the repository's config is loaded.
  • changelog validate converts before validating. Converted entries have no products, so a missing products is accepted when products.default is set.
  • changelog upload uploads the converted entry, so the pool holds docs-builder entries from then on.
  • Commit-range bundling reads a pool entry in the docs-builder format first and falls back to the repository's format, which covers files uploaded before it set entry_format. A pool entry without products takes them like a synthesized entry: pivot.products labels, then products.default. Those PRs now have their metadata fetched for that.
• Timestamped file names. A format with files: any (elastic-agent-changelog-tool) has file names that don't carry the PR. changelog validate assigns such a file to the PR that adds it; changelog upload looks up the PR that added each file that names none (commits?path= then commits/{sha}/pulls) and uploads the entry under that PR's number; commit-range bundling matches a pool entry that still names no PR to the PR in the range that added a file with that name (one pulls/{n}/files call per PR without a pool entry, only when such entries exist).
• Docs: an "Other entry formats" section in create.md, entry_format in configure-ref.md, and a commented line in changelog.example.yml.

Checks

• Elastic.Changelog.Tests: 1670/1670 pass. New tests cover both shipped formats, a format defined in the test, unknown source keys and target fields, the config key, upload conversion, validation, and a commit-range bundle with a mixed pool (two Elasticsearch-format entries, one resolved by products.default and one by a label, plus one docs-builder entry). Without entry_format, an Elasticsearch-format pool entry still fails to parse, as before.
• docs-builder --path docs --strict: 0 errors.
• I ran the locally built changelog validate over all 715 files in elastic/elasticsearch with its docs/changelog.yml plus entry_format: elasticsearch: 697 pass. The other 18 used the schema area Snapshot/Restore; the format now translates it and Extract&Transform to the names the Elasticsearch config uses, and with [DOCS] Read changelog entries with the elasticsearch entry format elasticsearch#162667 all 718 files on main pass.
• Every top-level key in the current beats, elastic-agent and fleet-server fragments is covered by elastic-agent-changelog-tool.

Not covered

• Other bundling paths (changelog bundle with a product filter, outside a commit range) don't add products to converted entries.
• The upload step in elastic/docs-actions (changelog/upload) doesn't pass GITHUB_TOKEN to docs-builder yet, so the upload-time PR lookup would run unauthenticated until it does. That's a one-line follow-up there.
• Elasticsearch's 772 pool files stay in their format until they are re-uploaded. Range bundling reads them through the fallback meanwhile.

Fixes elastic/docs-eng-team#1106

🤖 Generated with Claude Code

https://claude.ai/code/session_01TjZFCvQhL3DdrcjFKU6jDT

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4528/

Sample changed pages:

• docs/data/release-notes/configure-ref.md
• docs/data/release-notes/create.md

[theletterf]

@Mpdreamz Ready to review

[theletterf]

@Mpdreamz Let's mothball this one till repos decide on whether to use a changelog file without following our standard, I'd say. This still means we might have to rewrite all existing .yml files though.