From 0d45e7d01b69ff6683f997b1a5831220704d91fb Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 19 May 2026 16:45:19 -0700 Subject: [PATCH 1/2] Edit changelog publish docs --- docs/cli/changelog/cmd-render.md | 64 ---------- docs/contribute/create-changelogs.md | 22 ++++ docs/contribute/publish-changelogs.md | 164 +++++++++++--------------- 3 files changed, 93 insertions(+), 157 deletions(-) diff --git a/docs/cli/changelog/cmd-render.md b/docs/cli/changelog/cmd-render.md index 51f4a37973..856d47047d 100644 --- a/docs/cli/changelog/cmd-render.md +++ b/docs/cli/changelog/cmd-render.md @@ -20,70 +20,6 @@ The `changelog render` command does **not** use `rules.publish` for filtering. F : `--title` The title to use for section headers, directories, and anchors in output files. Defaults to the version in the first bundle. When omitted, ISO date targets are formatted for display the same way as the `{changelog}` directive (for example, `2026-05-04` becomes "May 4, 2026", `2026-05` becomes "May 2026"), while directory names and heading anchors continue to use the raw target slug. If the string contains spaces, they are replaced with dashes when used in directory names and anchors. -## Output formats - -### Markdown - -The default output (`--file-type markdown`) generates multiple files: - -- `index.md` — features, enhancements, bug fixes, security updates, documentation changes, regressions, and other changes -- `breaking-changes.md` — breaking changes -- `deprecations.md` — deprecations -- `known-issues.md` — known issues -- `highlights.md` — highlighted entries (only created when at least one entry has `highlight: true`) - -### Asciidoc - -When `--file-type asciidoc` is specified, the command generates a single asciidoc file with all sections: - -- Security updates -- Bug fixes -- Highlights (only included when at least one entry has `highlight: true`) -- New features and enhancements -- Breaking changes -- Deprecations -- Known issues -- Documentation -- Regressions -- Other changes - -The asciidoc output uses attribute references for links (for example, `{repo-pull}NUMBER[#NUMBER]`). - -AsciiDoc output ignores the `--dropdowns` flag and always uses a standardized format with the following characteristics: - -- Multi-block entries (containing description, Impact, and Action sections) use proper list continuation markers (`+`) to maintain list structure -- Strong text formatting uses idiomatic single asterisk syntax (`*Impact:*`, `*Action:*`) following AsciiDoc best practices -- All content blocks are properly attached to their parent list items for correct rendering. - -### GFM format - -When `--file-type gfm` is specified, the command generates a single GitHub Flavored Markdown file optimized for GitHub releases: - -- `changelog.md` - Contains all sections in a single file with clean headings -- Clean section headings without anchor links (for example, `### Features and enhancements`) -- Simplified structure focused on readability -- Suitable for copy/pasting into GitHub releases - -The GFM output includes the following sections in order when entries are present: - -- Highlights (only included when at least one entry has `highlight: true`) -- Features and enhancements -- Breaking changes -- Deprecations -- Bug fixes (includes security updates) -- Known issues -- Documentation -- Regressions -- Other changes - -### Multiple PR and issue links - -Changelog entries can reference multiple pull requests and issues via the `prs` and `issues` array fields. All links are rendered inline: - -```md -* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) [#136900](https://github.com/elastic/elastic/pull/136900) -``` - ## Examples ```sh diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index 3d08b10790..22c750a969 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -176,6 +176,28 @@ The option precedence is: CLI option > `changelog.yml` bundle section > built-in You can use the `docs-builder changelog gh-release` command as a one-shot alternative to `changelog add` and `changelog bundle` commands. The command parses the release notes, creates one changelog file per pull request found, and creates a `changelog-bundle.yaml` file — all in a single step. Refer to [](/cli/changelog/gh-release.md). +### Release highlights + +Some teams have historically had a dedicated page for release highlights. +To accommodate this behavior, changelogs have an optional `highlight` boolean field. +Highlights are most commonly used for major or minor version releases to draw attention to the most important changes. +Any type of changelog (such as features, enhancements, or bug fixes) can be a highlight, though they're typically associated with `type: feature`. + +Example changelog for a release highlight: + +```yaml +type: feature +products: +- product: elasticsearch + target: 9.4.0 + lifecycle: ga +title: ES|QL Views support +description: 'ES|QL now supports Views: virtual indices whose fields are produced by an ES|QL query. A view is referenced inside a FROM clause exactly like a regular index....' +highlight: true +``` + +When you set `highlight: true` in a changelog, it appears in both the highlights page (for example, `highlights.md` in markdown output) and its normal type section (for example, `index.md`). + ## Next steps After you've created a changelog files, you can gather them into [release bundles](/contribute/bundle-changelogs.md). diff --git a/docs/contribute/publish-changelogs.md b/docs/contribute/publish-changelogs.md index 6aa62ab0cb..25bc9a3de6 100644 --- a/docs/contribute/publish-changelogs.md +++ b/docs/contribute/publish-changelogs.md @@ -1,135 +1,113 @@ # Publish changelogs -The structure of the changelogs and bundle files is designed to be as stable and consistent as possible so that all teams can incorporate it into their workflow. +You can use release bundles to generate documentation in multiple formats: -The process for deriving docs from the bundle files is designed to be a separate workflow, so that content contributors do not need to worry about layout changes over time. +- [Asciidoc](#asciidoc) for Elastic 8.x documentation +- [Elastic Docs V3](#docs-v3) for Elastic 9.x and later documentation +- [GFM](#gfm) for GitHub release notes :::{note} In the short term, the goal is to create docs that can be included in [existing release note pages](https://www.elastic.co/docs/release-notes). In the longer term, the goal is to move to more filterable, dynamic pages. ::: -## Include changelogs inline [changelog-directive] +## Before you begin -You can use the [`{changelog}` directive](/syntax/changelog.md) to render all changelog bundles directly in your documentation pages. +1. [Create a changelog configuration file](/contribute/configure-changelogs.md) to define all the default behavior and optional profiles and rules. +1. [Create changelogs](/contribute/create-changelogs.md) that describe all the notable changes. +1. [Bundle the changelogs](/contribute/bundle-changelogs.md) for product releases. -```markdown -:::{changelog} -::: -``` - -By default, the directive renders all bundles from `changelog/bundles/` (relative to the docset root), ordered by semantic version (newest first). -For full documentation and examples, refer to the [{changelog} directive syntax reference](/syntax/changelog.md). - -:::{note} -All product-specific filtering must be configured at bundle time via `rules.bundle`. Unlike the `changelog render` command, the directive does not apply `rules.publish`. -::: +## Create asciidoc output [asciidoc] -## Generate markdown or asciidoc [render-changelogs] - -The `docs-builder changelog render` command creates markdown or asciidoc files from changelog bundles for documentation purposes. -For up-to-date details, use the `-h` command option or refer to [](/cli/changelog/render.md). - -Before you can use this command you must create changelog files and collect them into bundles. -For example, the `docs-builder changelog bundle` command creates a file like this: - -```yaml -products: -- product: elasticsearch - target: 9.2.2 -entries: -- file: - name: 1765581721-convert-bytestransportresponse-when-proxying-respo.yaml - checksum: d7e74edff1bdd3e23ba4f2f88b92cf61cc7d490a -- file: - name: 1765581721-fix-ml-calendar-event-update-scalability-issues.yaml - checksum: dfafce50c9fd61c3d8db286398f9553e67737f07 -- file: - name: 1765581651-break-on-fielddata-when-building-global-ordinals.yaml - checksum: 704b25348d6daff396259216201053334b5b3c1d -``` - -To create markdown files from this bundle, run the `docs-builder changelog render` command: +If you need Asciidoc output (for example, for [Elastic 8.x and earlier docs](https://www.elastic.co/guide/index.html)), you can use the `docs-builder changelog render` command with `--file-type asciidoc`. +For example: ```sh docs-builder changelog render \ - --input "/path/to/changelog-bundle.yaml|/path/to/changelogs|elasticsearch|keep-links,/path/to/other-bundle.yaml|/path/to/other-changelogs|kibana|hide-links" \ <1> - --title 9.2.2 \ <2> - --output /path/to/release-notes \ <3> - --subsections <4> + --input "./docs/releases/changelog-bundle.yaml" \ + --output ./docs/release-notes \ + --file-type asciidoc \ + --subsections <1> ``` -1. Provide information about the changelog bundle(s). The format for each bundle is `"|||"` using pipe (`|`) as delimiter. To merge multiple bundles, separate them with commas (`,`). Only the `` is required for each bundle. The `` is useful if the changelogs are not in the default directory and are not resolved within the bundle. The `` is necessary if your changelogs do not contain full URLs for the pull requests or issues. The `` can be `hide-links` or `keep-links` (default) to control whether PR/issue links are hidden for changelogs from private repositories. -2. The `--title` value is used for an output folder name and for section titles in the output files. If you omit `--title` and the first bundle contains a product `target` value, that value is used. Otherwise, if none of the bundles have product `target` fields, the title defaults to "unknown". -3. By default the command creates the output files in the current directory. -4. By default the changelog areas are not displayed in the output. Add `--subsections` to group changelog details by their `areas`. For breaking changes that have a `subtype` value, the subsections will be grouped by subtype instead of area. +1. You can choose to group the changelogs by their `areas`. Otherwise, they are grouped only by `type`. -:::{important} -Paths in the `--input` option must be absolute paths or use environment variables. Tilde (`~`) expansion is not supported. -::: +The command generates a single output file that includes all types of changelogs. +For up-to-date details, use the `-h` command option or refer to [](/cli/changelog/render.md). -For example, the `index.md` output file contains information derived from the changelogs: +## Create Elastic Docs V3 output [docs-v3] -```md -## 9.2.2 [elastic-release-notes-9.2.2] +If you need [Elastic Docs V3](/index.md) output, you have two options: + +- [Publish bundles directly](#changelog-directive) with the `{changelog}` directive +- [Create markdown output](#render-changelogs) for each release bundle -### Fixes [elastic-9.2.2-fixes] +The first option is simplest since it requires only a one-time change to your existing release docs. -**Network** -* Convert BytesTransportResponse when proxying response from/to local node. [#135873](https://github.com/elastic/elastic/pull/135873) +### Publish bundles directly [changelog-directive] -**Machine Learning** -* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) [#136900](https://github.com/elastic/elastic/pull/136900) +You can use the [`{changelog}` directive](/syntax/changelog.md) to derive docs from your release bundles. +For example, update your existing release note page to include a directive like this: -**Aggregations** -* Break on FieldData when building global ordinals. [#108875](https://github.com/elastic/elastic/pull/108875) +```md +:::{changelog} /path/to/bundles +:type: all <1> +:subsections: <2> +::: ``` -When a changelog includes multiple values in its `prs` or `issues` arrays, all its links are rendered inline, as shown in the Machine Learning example above. +1. If you have separate release note pages for each type, you can edit this option to show the appropriate subset on each page. +2. You can choose to group the changelogs by their `areas`. Otherwise, they are grouped only by `type`. -To comment out the pull request and issue links, for example if they relate to a private repository, add `hide-links` to the `--input` option for that bundle. -This allows you to selectively hide links per bundle when merging changelogs from multiple repositories. -When `hide-links` is set, all PR and issue links for affected changelogs are hidden together. +There are also options that affect whether to use dropdowns, include descriptions, hide links, and more. +For full documentation and examples, refer to the [{changelog} directive syntax reference](/syntax/changelog.md). -If you have changelogs with `feature-id` values and you want them to be omitted from the output, use the `--hide-features` option. Feature IDs specified via `--hide-features` are **merged** with any `hide-features` already present in the bundle files. This means both CLI-specified and bundle-embedded features are hidden in the output. +### Create markdown output [render-changelogs] -To create an asciidoc file instead of markdown files, add the `--file-type asciidoc` option: +If you need Markdown output (in particular, the [custom syntax](/syntax/index.md) used in Elastic documentation), you can use the `docs-builder changelog render` command with `--file-type markdown`. +For example: ```sh docs-builder changelog render \ - --input "./changelog-bundle.yaml,./changelogs,elasticsearch" \ - --title 9.2.2 \ - --output ./release-notes \ - --file-type asciidoc \ <1> - --subsections +--input "./kibana/docs/releases/cloud-serverless/2026-05-12.yaml" \ +--output ./docs-content/release-notes/elastic-cloud-serverless/_snippets \ +--config ./docs-content/changelog.yml \ +--file-type markdown ``` -1. Generate a single asciidoc file instead of multiple markdown files. +The command generates multiple output files: + +- `index.md` — features, enhancements, bug fixes, security updates, documentation changes, regressions, and other changes +- `breaking-changes.md` — breaking changes +- `deprecations.md` — deprecations +- `known-issues.md` — known issues +- `highlights.md` — highlighted entries (only created when at least one entry has `highlight: true`) + +For up-to-date details, use the `-h` command option or refer to [](/cli/changelog/render.md). -## Release highlights +If you are adding this content to existing release note pages, use [file inclusions](/syntax/file_inclusion.md). +For example, each time you create a new set of markdown files, you must include it into the existing docs like this: -The `highlight` field allows you to mark changelogs that should appear in a dedicated highlights page. -Highlights are most commonly used for major or minor version releases to draw attention to the most important changes. +```md +:::{include} _snippets/2026-05-12/index.md +::: +``` -When you set `highlight: true` in a changelog: +Since this method requires generating files and adding file inclusions for each release, it's preferrable to [publish bundles directly](#changelog-directive). -- It appears in both the highlights page (`highlights.md`) and its normal type section (for example "Features and enhancements") -- The highlights page is only created when at least one changelog has `highlight: true` (unlike other special pages like `known-issues.md` which are always created) -- Highlights can be any type of changelog (features, enhancements, bug fixes, etc.) +## Create GFM output [gfm] -Example changelog with highlight: +If you need GitHub Flavored Markdown (GFM) output, you can use the `docs-builder changelog render` command with `--file-type gfm`. +For example: -```yaml -type: feature -products: -- product: elasticsearch - target: 9.3.0 - lifecycle: ga -title: New Cloud Connect UI for self-managed installations -description: Adds Cloud Connect functionality to Kibana, which allows you to use cloud solutions like AutoOps and Elastic Inference Service in your self-managed Elasticsearch clusters. -highlight: true +```sh +docs-builder changelog render \ + --input "./docs/bundles/1.10.0.yaml" \ + --output ./docs/github-release \ + --file-type gfm ``` -When rendering, changelogs with `highlight: true` are collected from all types and rendered in a dedicated highlights section. -In markdown output, this creates a separate `highlights.md` file. -In asciidoc output, highlights appear as a dedicated section in the single asciidoc file. +The command generates a single GitHub Flavored Markdown file that includes all types of changelogs. +It has clean section headings and is suitable for copying and pasting into GitHub releases. + +For up-to-date details, use the `-h` command option or refer to [](/cli/changelog/render.md). \ No newline at end of file From 1f8ad0572f5314e57cb5f9573e2d322c767d0855 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 19 May 2026 19:27:47 -0700 Subject: [PATCH 2/2] Fix typo --- docs/contribute/publish-changelogs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/publish-changelogs.md b/docs/contribute/publish-changelogs.md index 25bc9a3de6..1e8ded2e16 100644 --- a/docs/contribute/publish-changelogs.md +++ b/docs/contribute/publish-changelogs.md @@ -93,7 +93,7 @@ For example, each time you create a new set of markdown files, you must include ::: ``` -Since this method requires generating files and adding file inclusions for each release, it's preferrable to [publish bundles directly](#changelog-directive). +Since this method requires generating files and adding file inclusions for each release, it's preferable to [publish bundles directly](#changelog-directive). ## Create GFM output [gfm]