Writing Good Changelogs #
Your changelog helps customers decide whether to update.
What to Include #
| Section | Content |
|---|---|
| Breaking Changes | Things that might break existing setups |
| New Features | New functionality added |
| Improvements | Enhancements to existing features |
| Bug Fixes | Problems that were resolved |
| Requirements | System requirement changes |
Good Changelog Example #
What’s New in Version 2.0.0 #
IMPORTANT: This is a major update with breaking changes. Please backup before updating.
Breaking Changes:
- Removed support for PHP 7.2 (now requires PHP 7.4+)
- Old API v1 endpoints no longer work
New Features:
- Advanced reporting dashboard with charts
- Export data to CSV, Excel, or PDF
- New customer portal dashboard
Improvements:
- 50% faster license validation
- Better error messages throughout
- Mobile-responsive admin interface
Bug Fixes:
- Fixed: Renewals not sending email notifications
- Fixed: Special characters in product names
- Fixed: Time zone issues in reports
Bad Changelog Example #
- Various bug fixes
- Performance improvements
- Updated libraries
Why it’s bad: Customers can’t tell what changed or if they should update.
Tips #
- Use customer-facing language (not technical jargon)
- Be specific about what changed
- Organize by category (New, Improved, Fixed)
- Highlight breaking changes at top
- Explain WHY to update
Related Topics #
- [Creating a New Version](#)
- [Version Settings](#)
- [Semantic Versioning](#)