elastic / elastic/docs-builder
"changelog add" docs and CLI help still show versioned --products
- 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
Assessment
This issue has not been assessed yet.