Skip to content

[DOCS] Read changelog entries with the elasticsearch entry format - #162667

Draft
theletterf wants to merge 1 commit into
elastic:mainfrom
theletterf:docs/release-notes-entry-format
Draft

theletterf wants to merge 1 commit into
elastic:mainfrom
theletterf:docs/release-notes-entry-format

Conversation

@theletterf

Copy link
Copy Markdown
Member

This gets Elasticsearch ready for the shared release notes automation without changing how anyone writes changelog entries.

Today docs-builder can't read the files in docs/changelog/, because they use the Elasticsearch format (summary, area, the breaking/deprecation/highlight blocks) rather than docs-builder's. elastic/docs-builder#4528 adds entry formats that a repository selects in its changelog.yml, and ships an elasticsearch format based on build-tools-internal/src/main/resources/changelog-schema.json.

What this PR changes:

  • docs/changelog.yml: sets entry_format: elasticsearch, and adds the five schema areas that had no pivot.areas key (DLM, Features, Graph, Ingest, Java High Level REST Client) without labels, so entries that use them validate. The format already translates Snapshot/Restore and Extract&Transform to the names this file uses.
  • .github/workflows/release-notes.yml: the shared caller from elastic/docs-actions. On pull requests it checks the type label and validates any entry file the PR adds; on push to main it uploads the entries, converted, to the changelog pool that unified and Serverless release notes read.

I checked it with a local build of #4528: all 718 files in docs/changelog/ on main validate with this config, and the label check passed 298 of the last 300 merged PRs (one had no type label, one had two).

Don't merge yet. entry_format is a new key, and docs-builder releases before #4528 reject unknown keys, so this has to wait until #4528 is merged and in the edge build that the workflows and the Serverless promotion use. I'll mark it ready then.

Not in this PR: release-notes / validate isn't a required check. If it becomes one, the caller needs a merge_group trigger for the merge queue.

Related to elastic/docs-eng-team#1106

🤖 Generated with Claude Code

https://claude.ai/code/session_01TjZFCvQhL3DdrcjFKU6jDT

Set entry_format: elasticsearch in docs/changelog.yml so docs-builder
converts the entry files in docs/changelog, and list the changelog schema
areas that had no pivot.areas key. Add the shared release-notes workflow,
which validates entry files and labels on pull requests and uploads the
converted entries on push to main.

Related to elastic/docs-eng-team#1106

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TjZFCvQhL3DdrcjFKU6jDT
@theletterf theletterf added >non-issue Team:Docs Meta label for docs team :Docs/General Docs team request — other / unspecified v9.6.0 labels Oct 20, 2026
@elasticsearchmachine elasticsearchmachine added the external-contributor Pull request authored by a developer outside the Elasticsearch team label Oct 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🔍 Preview links for changed docs

⏳ Building and deploying preview... View progress

This comment will be updated with preview links when the build is complete.

@theletterf
theletterf marked this pull request as ready for review October 20, 2026 13:03
@theletterf
theletterf requested a review from a team as a code owner October 20, 2026 13:03
@elasticsearchmachine

Copy link
Copy Markdown
Collaborator

Pinging @elastic/core-docs (:Docs/General)

@elasticsearchmachine

Copy link
Copy Markdown
Collaborator

Pinging @elastic/core-docs (Team:Docs)

@github-actions

Copy link
Copy Markdown
Contributor

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

This branch was successfully deployed

1 active deployment
docs-preview — dd5d4037 Deployed Oct 20, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

:Docs/General Docs team request — other / unspecified external-contributor Pull request authored by a developer outside the Elasticsearch team >non-issue Team:Docs Meta label for docs team v9.7.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants