changelog

name	changelog
description	Style rules for updating CHANGELOG.md entries. Use whenever the user asks to update, add to, or write entries in CHANGELOG.md.
user-invocable	false

CHANGELOG Style

CHANGELOG.md entries are read by end users (Salesforce admins, devs, ops) deciding whether to upgrade. They are not internal dev notes.

Rules

• Stay concise. One short bullet per change. One sentence is the target. No paragraphs.
• Write for end users, not developers. Describe the user-visible behavior or capability, not the implementation.
  • YES: "More engaging intro on the generated documentation home page."
  • NO: "The welcomeToDocumentation i18n key now teases what is browsable..."
  • NO: "Translated to all 9 locales (de, en, es, fr, it, ja, nl, pl, pt-BR)." (mention only if it is the change itself, e.g. "Added German translations")
• Skip implementation details unless they directly affect the user: file paths, function names, i18n keys, internal flags, refactor mechanics.
• Link the command when the entry applies to a specific command, using the standard format [hardis:topic:action](https://sfdx-hardis.cloudity.com/hardis/topic/action/).
• Always group updates by command. A command must appear at most once in a section. If it already has an entry (or you are adding several changes to the same command), write the command link once and put each change as a nested bullet under it - never repeat the same command link on multiple top-level lines. A single change stays on one line: [command](url): <change>.
• Add entries under ## [beta] (main) at the top of the file. Do not create version sections - releases set those.

Pattern

Single change for a command:

- [hardis:topic:action](https://sfdx-hardis.cloudity.com/hardis/topic/action/): <one short sentence about user-visible change>.
- <Site / generic change>: <one short sentence>.

Multiple changes for the same command - group them under one command link:

- [hardis:topic:action](https://sfdx-hardis.cloudity.com/hardis/topic/action/):
  - <one short sentence about the first user-visible change>.
  - <one short sentence about the second user-visible change>.

Each nested bullet must be end-user relevant (a new flag, a new channel, a new default, a fixed behavior). Never use sub-bullets to list affected files or locales.