Changelog Writing
Changelog Format
User-Facing
- Lead with benefit: "You can now export to PDF" not "Added PDF export module."
- Group: New, Improved, Fixed.
- Skip internal changes users don't care about.
- Link to docs for new features.
Developer-Facing
- Follow Keep a Changelog format.
- Group: Added, Changed, Deprecated, Removed, Fixed, Security.
- Reference issue/PR numbers.
- Highlight breaking changes prominently.
Semantic Versioning Communication
- Major (2.0): "Big update" — migration guide required.
- Minor (1.5): "New features" — backwards compatible.
- Patch (1.5.1): "Bug fixes" — no new features.
Anti-Patterns
- "Various bug fixes and performance improvements" — be specific.
- Technical jargon in user-facing notes.
- No date on entries.
- Changelog that's just git commit messages.