elastic / elastic/docs-builder

"changelog add" docs and CLI help still show versioned --products

Open
#3,956 0 comments 0 reactions 1 assignee Claimed by @lcawl View on GitHub
needs triage
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Describe the bug

`changelog add` no longer accepts a version in `--products` (applicability comes from the origin branch; versioned PR-less items belong on `changelog note`). CLI help and several docs pages still teach the old `"product version lifecycle"` form, so a command copied from the docs fails and creates **zero** files.

That is made worse by CLI diagnostics: file-less errors, warnings, and skip summaries look equally fatal (see #3726), so it is hard to tell which messages actually prevent changelog creation.

Related: https://github.com/elastic/docs-builder/issues/3726

## Expected behavior

1. **Docs and `-h` match current `changelog add` behavior.** `--products` examples should be product IDs only (optional lifecycle), e.g. `"cloud-serverless, kibana"`. Version/date in the middle slot should be documented as an error for `add` and as required for `changelog note`.
2. **Diagnostics should make blast radius obvious.** Messages that abort writes (e.g. `ValidateNoVersionTarget`) should be clearly errors. GitHub fetch failures without `--strict-fetch` should remain warnings and not look like unhandled exceptions. `rules.create` skips should stay skips. A bulk `add` should not imply files were written when validation failed first.

## Steps to reproduce

```sh
docs-builder changelog add \
--prs ./docs/temp/prs.txt \
--concise \
--products "cloud-serverless 2026-08-27, kibana"
```

Typical output mix:

- **Error** (this is what prevents creation): `Product 'cloud-serverless' specifies version(s) '2026-08-27', but changelog entries do not carry version applicability…`
- **Warning** (does not abort writes by itself): `N of M pull request(s) could not be fetched from GitHub. Their changelogs were created without rules.create…` — this text is also stale when validation later fails, because no files were created.
- **Info**: `Processed 0 PR(s) successfully, skipped …, … could not be fetched`

Because those file-less diagnostics go through `DisplayGlobalDiagnostics` (`ErrataFileSourceRepository.cs`) they can all appear in a red **"Unhandled exception"** panel (#3726).

## Outdated help / docs (non-exhaustive)

These still show or describe versioned `--products` for `changelog add`:

- `src/tooling/docs-builder/Commands/ChangelogCommand.cs` (`Add` `--products` param docs → `-h`)
- `docs/cli/changelog/cmd-add.md` (option text, filename examples, product-format examples vs the later note that versions are an error)
- `docs/data/release-notes/create.md` (minimal example, batch `--prs` example, `--release-version` text that still says entries get `target: 1.34.0`, highlight YAML with `target:`)

Keep versioned product specs where they are still valid (`changelog note`, `bundle`/`remove` filters).

## Proposed fix

**Docs / help**

- Align `changelog add` `--products` with `ValidateNoVersionTarget`.
- Point versioned, PR-less items at `changelog note`.
- Fix contradictory examples on the same page (`cmd-add.md` currently shows both “include a version” and “version is an error”).

**Diagnostics** (overlap with #3726)

- Do not put ordinary warnings under “Unhandled exception”.
- Distinguish: **error** = no file / command fails; **warning** = file still written (or skip); **skip** = `rules.create`.
- Don’t say fetch-failed changelogs “were created” when a later validation error meant nothing was written.

## Tooling

- [x] docs-builder

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.