Skip to content

Conversation

@lcawl
Copy link
Contributor

@lcawl lcawl commented Jan 3, 2026

Relates to elastic/docs-builder#2350

This PR adds a changelog configuration file, which contains things like the label to area mappings that will affect the creation of release notes per https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/changelog

Most of the existing "areas" were derived from https://github.com/elastic/elasticsearch/blob/main/build-tools-internal/src/main/resources/changelog-schema.json
There were some area labels and types for which I couldn't currently find a mapping in https://github.com/elastic/elasticsearch-serverless/labels so I've commented them out for now.

Examples

To test the use of this configuration file:

  1. Install docs-builder.

  2. Run the docs-builder changelog add command to generate changelogs for a PR that uses the type and area labels that are included in the changelog.yml. For example:

    ./docs-builder changelog add --pr 140034 --repo elasticsearch --owner elastic \
      --products "elasticsearch 9.3.0" --output ./elasticsearch/docs/changelog/ \
      --config ./elasticsearch/docs/changelog.yml
    
    ./docs-builder changelog add --pr 139703 --repo elasticsearch --owner elastic \
      --products "elasticsearch 9.3.0" --output ./elasticsearch/docs/changelog/ \
      --config ./elasticsearch/docs/changelog.yml
  3. Check out Add PR label blockers to changelog creation docs-builder#2350 then refresh the docs-builder binaries per the readme:

    ./build.sh clean
    ./build.sh publishbinaries
  4. Uncomment the add_blockers section of the changelog.yml file.

  5. Run the docs-builder changelog add command to test the add_blockers clause. For example, from the .artifacts/publish/docs-builder/release in the docs-builder repo:

    ./docs-builder changelog add --pr https://github.com/elastic/elasticsearch/pull/140227  \
      --products "elasticsearch 9.3.0" --config ~/path/to/elasticsearch/docs/changelog.yml \
      --output ~/path/to/elasticsearch/docs/changelog

    Re-comment the add_blockers section (unless that PR gets merged).

  6. Checkout Add changelog bundle and render commands docs-builder#2341 then refresh the docs-builder binaries (per earlier step).

  7. Uncomment the render_blockers section of the changelog.yml file.

  8. Run the docs-builder changelog bundle and docs-builder changelog render commands to generate docs that heed the render_blockers config. For example, from the .artifacts/publish/docs-builder/release in the docs-builder repo:

    ./docs-builder changelog bundle --directory ~/path/to/elasticsearch/docs/changelog --all
    ./docs-builder changelog render --input ~/path/to/elasticsearch/docs/changelog/changelog-bundle.yaml --output ~/path/to/elasticsearch/docs/release-notes/_snippets

@github-actions
Copy link
Contributor

github-actions bot commented Jan 3, 2026

ℹ️ 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

>docs General docs changes v9.3.0 v9.4.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants