Skip to content

Conversation

@lcawl
Copy link
Contributor

@lcawl lcawl commented Jan 16, 2026

This PR is a test of the docs-builder changelog add, bundle, and render commands, which are documented in https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/changelog

In particular, it contains output files generated with the following fixes and enhancements applied elastic/docs-builder#2485 and elastic/docs-builder#2481

NOTE: The changelogs with the new format are put in a "new" sub-folder for the purposes of this test but that's not an indication of where they'll be stored in the long-term.

Procedure

This content was created by following these steps:

  1. Re-create the changelogs with the new format. For example:
     docs-builder changelog add \
     --prs ./docs/elasticsearch-9.3.0.txt \
     --repo elasticsearch --owner elastic \
     --products "elasticsearch 9.3.0" \
     --config ./docs/changelog.yml \
     --output ./docs/changelog/new/ \
     --use-pr-number --strip-title-prefix
    Note that three of the PRs will fail to create changelogs due to their labels (i.e. two have the >non-issue label and one is missing any "type" labels).
  2. Create a bundle of all the changelogs. This can be done based on a PR list, the changelog product metadata, or all changelogs in a folder. For example, based on PR list:
    docs-builder changelog bundle \
    --directory ./elasticsearch/docs/changelog/new \
    --output ./docs/release-notes/changelog-bundles/9.3.0.yaml \
    --prs ./docs/elasticsearch-9.3.0.txt \
    --output-products "elasticsearch 9.3.0 ga"
    Note that it will return a warning because of the three missing changelogs.
  3. Render the bundle as markdown snippets:
    docs-builder changelog render \
    --config ./docs/changelog.yml \
    --input "/path/to/elasticsearch/docs/release-notes/changelog-bundles/9.3.0.yaml|/path/to/elasticsearch/docs/changelog/new|elasticsearch|keep-links" \
    --output ./docs/release-notes/_snippets/ \
    --subsections
  4. Add references to these snippets in the existing release note docs.

@github-actions
Copy link
Contributor

@github-actions
Copy link
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?

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants