What exactly is a changelog?
A changelog is a file or page that contains a curated, chronologically ordered list of notable changes for each version of a project. Unlike a commit log, a changelog is written for humans — not machines.
Its purpose is to communicate what changed, why it matters, and what users need to know. A good changelog builds trust and reduces support requests.
Why does every product need a changelog?
- Transparency — Users see that your product is actively maintained and improving.
- Trust — Honest communication about changes — including breaking ones — builds long-term trust.
- Fewer support tickets — Users find answers about recent changes before contacting support.
- Feature adoption — Users discover new features they would otherwise miss.
How to structure a changelog
Group your changes into categories so readers can quickly find what matters to them:
- Added — New features or capabilities
- Changed — Changes to existing functionality
- Fixed — Bug fixes
- Removed — Features or endpoints that have been removed
- Security — Vulnerability fixes or security improvements
Changelog example
## [1.2.0] - 2026-04-01
### Added
- Dark mode support for the widget
- Email notifications for new entries
### Fixed
- Widget not loading on Safari 17
- Pagination offset error on project list
### Changed
- Improved API response times by 40%5 best practices
- Write for your audience, not your team. Use language your users understand.
- Be consistent. Use the same format and categories for every release.
- Keep it up to date. A stale changelog is worse than no changelog.
- Categorize changes. Group by type so readers can scan quickly.
- Make it easily accessible. Link it from your navigation, footer, or widget.
Tools for managing changelogs
While you can maintain a CHANGELOG.md file manually, tools like Deplyd make it easy to publish, distribute, and embed changelogs — with API access, email notifications, and a 1.8KB widget.