From d57b20eb49d4c5d29b60f7265de2714a1821a041 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 11 Sep 2026 13:13:49 -0500 Subject: [PATCH 1/3] [DOCS] Describe workflow for amending changelog bundle notes --- docs/cli/changelog/cmd-bundle-amend.md | 9 +++++ docs/cli/changelog/cmd-note.md | 9 ++++- docs/cli/changelog/cmd-remove.md | 2 +- docs/cli/changelog/cmd-upload.md | 2 + docs/data/release-notes/bundle.md | 39 ++++++++++++++++++- docs/data/release-notes/create.md | 1 + docs/data/release-notes/overview.md | 2 +- docs/development/changelog-bundle-registry.md | 8 +++- 8 files changed, 66 insertions(+), 6 deletions(-) diff --git a/docs/cli/changelog/cmd-bundle-amend.md b/docs/cli/changelog/cmd-bundle-amend.md index 78371adc72..6812d24712 100644 --- a/docs/cli/changelog/cmd-bundle-amend.md +++ b/docs/cli/changelog/cmd-bundle-amend.md @@ -11,6 +11,7 @@ Specify at least one of `--add` or `--remove`. To create a bundle, use [](/cli/changelog/bundle.md). For details and examples, go to [](/data/release-notes/bundle.md). +For changelog notes (`note-*.yml`) after a bundle has shipped, go to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). `--add` and `--remove` accept those files like any other changelog YAML. Don't use `--add` for a late note: upload the file and let the scrubber write `{parent}.amend-notes.yaml`. `--remove` does not unpublish the pool file. ## Output @@ -125,6 +126,14 @@ docs-builder changelog bundle-amend \ The CLI computes the checksum of the sourced YAML and matches it against the effective bundle (parent plus any existing amend files). If the bundle contains the file with a different checksum, or no YAML can be sourced (for example a git-ref entry that exists only in the bundle), the command fails unless you pass `--force` to remove by file name only. +`--remove` works the same for a changelog note (`note-*.yml`). That does not unpublish the pool file. For late notes and the scrubber-owned `.amend-notes` sidecar, refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). + +```sh +docs-builder changelog bundle-amend \ + ./docs/changelog/bundles/9.3.0.yaml \ + --remove /changelog/elastic/kibana/main/note-known-issue-aggregations.yml +``` + ### Add multiple changelogs to a bundle Comma-separated list: diff --git a/docs/cli/changelog/cmd-note.md b/docs/cli/changelog/cmd-note.md index b2bc6f1104..bcdc59f256 100644 --- a/docs/cli/changelog/cmd-note.md +++ b/docs/cli/changelog/cmd-note.md @@ -61,10 +61,17 @@ products: Upload is the same as for other changelog YAML files. An index at `changelog/{org}/{repo}/notes-{version}.json` lists every changelog "note" file that applies to each version. -If the release bundle for that product and version or date has already shipped when you upload, the scrubber generates an amend file so the changelog reaches published docs without a manual rerun. +If the release bundle for that product and version or date has already shipped when you upload, the scrubber generates a `{parent}.amend-notes.yaml` sidecar so the changelog reaches published docs without a manual rerun. Don't run `changelog bundle-amend --add` for that file. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). If there is no existing or planned bundle for that product and version or date, you can create a bundle from a path list that contains all the relevant changelogs. Refer to [Bundle by file paths](/cli/changelog/bundle.md#changelog-bundle-files). +## Remove a note from a published bundle [changelog-note-remove] + +`changelog remove` only deletes local YAML. It does not change a published bundle or the changelog pool. + +- If the note is already embedded in the parent bundle, use `changelog bundle-amend --remove` and upload the numbered sidecar. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). +- If the note exists only in `.amend-notes` (uploaded after the bundle shipped), no `changelog` command unpublishes it from the pool. Don't create, edit, or delete `.amend-notes` files. + ## Configuration checks The same configuration-file checks that apply to `changelog add` apply here: diff --git a/docs/cli/changelog/cmd-remove.md b/docs/cli/changelog/cmd-remove.md index 441553d72d..2373614d9f 100644 --- a/docs/cli/changelog/cmd-remove.md +++ b/docs/cli/changelog/cmd-remove.md @@ -7,7 +7,7 @@ Two mutually exclusive modes are available: - **Profile-based**: `docs-builder changelog remove ` — uses the same `bundle.profiles` configuration as [`changelog bundle`](/cli/changelog/bundle.md) to determine which changelogs to remove. - **Option-based**: `docs-builder changelog remove --products "..."` (or `--prs`, `--issues`, `--all`, `--release-version`, `--report`, `--files`) — specify the filter directly. -Bundles are self-contained (every entry is embedded inline), so removing changelog source files never affects existing bundles or the `{changelog}` directive. The command deletes matching files without any bundle dependency check. +Bundles are self-contained (every entry is embedded inline), so removing changelog source files never affects existing bundles or the `{changelog}` directive. The command deletes matching files without any bundle dependency check. That includes changelog notes (`note-*.yml`): local delete never drops a note from a published bundle or from a `.amend-notes` sidecar. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). For more context, go to [](/data/release-notes/bundle.md#changelog-remove). diff --git a/docs/cli/changelog/cmd-upload.md b/docs/cli/changelog/cmd-upload.md index 2ae4652953..43bc332361 100644 --- a/docs/cli/changelog/cmd-upload.md +++ b/docs/cli/changelog/cmd-upload.md @@ -4,6 +4,8 @@ Upload changelog entries or bundle artifacts to S3 or Elasticsearch. The command A downstream scrubber copies published objects to the public bucket and removes pull request and issue links that are not on the allowlist (unlike bundle-time `# PRIVATE:` sentinels on the private side). Those public bundles are less likely to work with [`changelog unpack`](/cli/changelog/unpack.md). +Uploading a `note-*.yml` file can cause the scrubber to create or update `{parent}.amend-notes.yaml` on the **public** bucket. This command does not write that sidecar. The command does not delete objects. There is no `changelog` subcommand that unpublishes a pool file. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). + To create bundles first, use [](/cli/changelog/bundle.md). For the end-to-end workflow, see [](/data/release-notes/bundle.md). diff --git a/docs/data/release-notes/bundle.md b/docs/data/release-notes/bundle.md index 79c1aa9cc2..5ad5fb424c 100644 --- a/docs/data/release-notes/bundle.md +++ b/docs/data/release-notes/bundle.md @@ -327,11 +327,48 @@ Don't explicitly list the amend bundles in the `--input` option of the `docs-bui For more details and examples, go to [](/cli/changelog/bundle-amend.md). +### Add or remove notes after a bundle ships [changelog-bundle-notes-after-ship] + +A changelog *note* is a `note-*.yml` file from [`changelog note`](/cli/changelog/note.md). Each product lists `products[].versions`. That file kind is not an entry `type` (notes still use types such as `known-issue` or `security`). + +When you create a release bundle from a PR list or GitHub release and the command is sourcing from the CDN, matching notes are already included. That automatic add does not apply to git-range bundles or `--force-local`. To build a bundle that contains only notes, use a [path list](/cli/changelog/bundle.md#changelog-bundle-files) (profile third argument or `--files`). + +#### Add a note after the bundle shipped + +1. Create the file with [`changelog note`](/cli/changelog/note.md). +2. Upload it with [`changelog upload --artifact-type changelog`](/cli/changelog/upload.md), using the same path and credentials as any other changelog YAML. +3. Stop. Don't run `changelog bundle-amend --add` for this file. + +The changelog scrubber writes `{parent}.amend-notes.yaml` (for example `9.3.0.amend-notes.yaml`) and merges it when the bundle is rendered. That suffix is reserved; you must not create, edit, or delete those files. + +#### Remove a note + +What you can do depends on where the note lives: + +| Where it is | What you can do today | +| --- | --- | +| Local file only; the bundle is not uploaded | [`changelog remove`](/cli/changelog/remove.md) or re-run `changelog bundle`. That never changes a published bundle. | +| Embedded in the parent bundle (or added with numbered `--add`) | `bundle-amend --remove` on the `note-*.yml` path, then upload `{parent}.amend-N.yaml` with [`changelog upload --artifact-type bundle`](/cli/changelog/upload.md). | +| Only in `.amend-notes` (uploaded after the bundle shipped) | No `changelog` command removes it from the published pool or that sidecar. Don't create, edit, or delete `.amend-notes` files. | + +Example of excluding a note that is already in the parent: + +```sh +docs-builder changelog bundle-amend \ + /bundle/kibana/9.3.0.yaml \ + --remove /changelog/elastic/kibana/main/note-known-issue-aggregations.yml \ + --output ./docs/releases +``` + +:::{warning} +`changelog bundle-amend --remove` does not unpublish the note YAML from the changelog pool. If that file is still published, the scrubber can treat it as a late note and write it back into `.amend-notes`. A checksum-strict `--remove` may not hide that restored copy. There is no docs-builder command that unpublishes a pool file. +::: + ## Remove changelog files [changelog-remove] A single changelog file might be applicable to multiple releases (for example, it might be delivered in both Stack and {{serverless-short}} releases or {{ech}} and Enterprise releases on different timelines). After it has been included in all of the relevant bundles, it is reasonable to delete the changelog to keep your repository clean. -Because bundles are self-contained, deleting changelog files never affects existing bundles or the docs built from them. +Because bundles are self-contained, deleting changelog files never affects existing bundles or the docs built from them. That includes changelog notes (`note-*.yml`): [`changelog remove`](/cli/changelog/remove.md) never drops a note from a published bundle or from a `.amend-notes` sidecar. Refer to [](#changelog-bundle-notes-after-ship). You can use the `docs-builder changelog remove` command to remove changelogs. If you created profiles, you can use them like this: diff --git a/docs/data/release-notes/create.md b/docs/data/release-notes/create.md index dc99833a90..88bfccf7b1 100644 --- a/docs/data/release-notes/create.md +++ b/docs/data/release-notes/create.md @@ -58,6 +58,7 @@ If you already have automated release notes for GitHub releases, you can use the These files don't have `prs` and thus don't appear in a release's PR list. The `products[].versions` are used to add these files to release bundles automatically. + After you upload a note, if that product version's bundle has already shipped, the scrubber attaches it without `changelog bundle-amend --add`. Taking a note off a published bundle is incomplete: there is no command that unpublishes the pool file. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). ::: Title, type, and products (including version or date) are the minimal details required when you are not deriving details from a PR. diff --git a/docs/data/release-notes/overview.md b/docs/data/release-notes/overview.md index d4f93eb8d9..1e225deffc 100644 --- a/docs/data/release-notes/overview.md +++ b/docs/data/release-notes/overview.md @@ -7,7 +7,7 @@ To use the `docs-builder changelog` commands in your development workflow: 1. [Configure changelogs](/data/release-notes/configure.md): Create a configuration file, map labels, and define rules for creation and bundling. 1. [Create changelogs](/data/release-notes/create.md) with `docs-builder changelog add` or `docs-builder changelog note` (depending on whether there's a PR associated with the change). - Alternatively, if you already have automated release notes for GitHub releases, you can use the `docs-builder changelog gh-release` command to create changelog files and a bundle from your GitHub release notes. Refer to [](/cli/changelog/gh-release.md). -1. [Bundle changelogs](/data/release-notes/bundle.md) with the `docs-builder changelog bundle` command. For example, create a bundle for the pull requests that are included in a product release. When changelogs are no longer needed in the repo, [remove changelog files](/data/release-notes/bundle.md#changelog-remove) with `docs-builder changelog remove`. +1. [Bundle changelogs](/data/release-notes/bundle.md) with the `docs-builder changelog bundle` command. For example, create a bundle for the pull requests that are included in a product release. To add or exclude changelog notes after a bundle has shipped, refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). When changelogs are no longer needed in the repo, [remove changelog files](/data/release-notes/bundle.md#changelog-remove) with `docs-builder changelog remove`. 1. [Publish release notes](/data/release-notes/publish.md): Use the `{changelog}` directive in docs or `docs-builder changelog render` to produce release documentation. For more information about running `docs-builder`, go to [Contribute locally](https://www.elastic.co/docs/contribute-docs/locally). diff --git a/docs/development/changelog-bundle-registry.md b/docs/development/changelog-bundle-registry.md index 7b217a28d7..b7dcbe53ed 100644 --- a/docs/development/changelog-bundle-registry.md +++ b/docs/development/changelog-bundle-registry.md @@ -74,7 +74,10 @@ narrowed reconciliation to the bundle tree): published bundle that lists all such late notes. The Lambda rebuilds it from current state on every reconcile, so redelivered events never produce duplicate amends. The `.amend-notes` suffix is **reserved** — do not create files with that suffix manually; see - [](/cli/changelog/bundle-amend.md). + [](/cli/changelog/bundle-amend.md). Public copies track private-bucket create and delete + events. Authors cannot issue those deletes through docs-builder today: `changelog upload` + does not delete objects, and `changelog remove` is local-only. For the author-facing + add and exclude path, see [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). - **Notes index** — `changelog/{org}/{repo}/notes-{version}.json`, one per version, **public bucket only**, produced by the scrubber Lambda's `NotesIndexReconciler`. See [Notes-index format](#notes-index-format) below. @@ -143,7 +146,8 @@ For each release version that has at least one note, the scrubber Lambda writes `bundle_seq` is derived — it is never authored and never a latch. The Lambda recomputes it on every reconcile by comparing the notes index against the set of entries in the published bundle and its -amend sidecars. +amend sidecars. Do not hand-edit `notes-{version}.json` or `.amend-notes` sidecars. Authors cannot +delete pool objects through docs-builder today. A 404 on a notes index means "no notes published for this version". An empty `notes` array never appears — the index is deleted rather than emptied, following the same From d665765e70ef9b2f363ff596133605761855c2ac Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 14 Sep 2026 17:45:51 -0500 Subject: [PATCH 2/3] Clarify misleading phrases --- docs/cli/changelog/cmd-bundle-amend.md | 2 +- docs/data/release-notes/bundle.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli/changelog/cmd-bundle-amend.md b/docs/cli/changelog/cmd-bundle-amend.md index 6812d24712..a388b27d3e 100644 --- a/docs/cli/changelog/cmd-bundle-amend.md +++ b/docs/cli/changelog/cmd-bundle-amend.md @@ -11,7 +11,7 @@ Specify at least one of `--add` or `--remove`. To create a bundle, use [](/cli/changelog/bundle.md). For details and examples, go to [](/data/release-notes/bundle.md). -For changelog notes (`note-*.yml`) after a bundle has shipped, go to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). `--add` and `--remove` accept those files like any other changelog YAML. Don't use `--add` for a late note: upload the file and let the scrubber write `{parent}.amend-notes.yaml`. `--remove` does not unpublish the pool file. +For changelog notes (`note-*.yml`) after a bundle has shipped, go to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). ## Output diff --git a/docs/data/release-notes/bundle.md b/docs/data/release-notes/bundle.md index 5ad5fb424c..a9cdb3ce3c 100644 --- a/docs/data/release-notes/bundle.md +++ b/docs/data/release-notes/bundle.md @@ -348,7 +348,7 @@ What you can do depends on where the note lives: | Where it is | What you can do today | | --- | --- | | Local file only; the bundle is not uploaded | [`changelog remove`](/cli/changelog/remove.md) or re-run `changelog bundle`. That never changes a published bundle. | -| Embedded in the parent bundle (or added with numbered `--add`) | `bundle-amend --remove` on the `note-*.yml` path, then upload `{parent}.amend-N.yaml` with [`changelog upload --artifact-type bundle`](/cli/changelog/upload.md). | +| Already in the parent or a numbered `amend-N` sidecar | `bundle-amend --remove` on the `note-*.yml` path, then upload `{parent}.amend-N.yaml` with [`changelog upload --artifact-type bundle`](/cli/changelog/upload.md). | | Only in `.amend-notes` (uploaded after the bundle shipped) | No `changelog` command removes it from the published pool or that sidecar. Don't create, edit, or delete `.amend-notes` files. | Example of excluding a note that is already in the parent: From 9b49f96a04320b076a8f736a028cf9f53597d1da Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 17 Sep 2026 23:51:54 -0500 Subject: [PATCH 3/3] Address review comment for cmd-note.md --- docs/cli/changelog/cmd-note.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/changelog/cmd-note.md b/docs/cli/changelog/cmd-note.md index bcdc59f256..9606745166 100644 --- a/docs/cli/changelog/cmd-note.md +++ b/docs/cli/changelog/cmd-note.md @@ -69,7 +69,7 @@ If there is no existing or planned bundle for that product and version or date, `changelog remove` only deletes local YAML. It does not change a published bundle or the changelog pool. -- If the note is already embedded in the parent bundle, use `changelog bundle-amend --remove` and upload the numbered sidecar. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). +- If the note is already in the parent bundle or a numbered `amend-N` sidecar, use `changelog bundle-amend --remove` and upload `{parent}.amend-N.yaml` with `changelog upload --artifact-type bundle`. Refer to [](/data/release-notes/bundle.md#changelog-bundle-notes-after-ship). - If the note exists only in `.amend-notes` (uploaded after the bundle shipped), no `changelog` command unpublishes it from the pool. Don't create, edit, or delete `.amend-notes` files. ## Configuration checks