Changelog Maintenance

Typical categories:

• Added
• Changed
• Fixed
• Deprecated
• Removed
• Security

Use categories that help readers understand impact, not categories copied blindly from commit history.

3. Write for the affected audience

Good release communication answers:

• what changed
• who should care
• whether action is required
• when an old path stops being safe
• where to find the canonical migration or domain documentation

4. Make deprecations actionable

If something is deprecated or removed, include:

• what replaces it
• by when consumers must move
• what breaks if they do not
• which canonical doc owns the new behavior

5. Keep the historical record trustworthy

Prefer:

• reverse chronological order
• dated entries
• reader-centered language
• links to the canonical docs for deeper detail

Changelog template

## [version] - YYYY-MM-DD

### Changed
- what changed
- who is affected

### Deprecated
- old path
- replacement
- migration deadline or expectation

### Migration
- required actions
- canonical doc links

Boundary rules

• changelog-maintenance owns communication, not semantic truth.
• If the meaning of a change is disputed, defer to the relevant product/domain/backend/frontend/platform owner.
• If the issue is broader document quality or doc structure, pair with ../technical-writing/SKILL.md.

Common changelog failures

• copying commit messages directly into release notes
• announcing behavior that the canonical spec does not actually define
• saying “various fixes” or “performance improvements” with no reader value
• listing breaking changes without migration guidance
• documenting every internal refactor as if users must care

Delivery checklist

• reader-facing impact is clear
• changes are categorized meaningfully
• migration/deprecation guidance exists where needed
• canonical owner docs are linked for semantic detail
• dates/order remain trustworthy