Changelog Writing

Changelog and release notes writing patterns including versioning communication and user-facing updates.

dragoon0x Updated

File contents

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.

dragoon0x/everything-design-taste/tree/main/skills/changelog-writing commit 45f5b62057

Frequently asked questions

npx skillmds@latest add dragoon0x/changelog-writing