Markdown Changelog Examples
A changelog records how a project evolves over time. Whether you're maintaining an open-source repository, shipping a SaaS product, or publishing API updates, a clear changelog helps users understand what's changed without comparing versions manually.
Releases • Version History • Bug Fixes • Breaking Changes • API Updates • Copy Ready
What Makes a Good Changelog?
A useful changelog answers one simple question:
"What's different in this version?"
It shouldn't describe every commit or every line of code that changed. Instead, it should highlight the updates that matter to the people using your project.
Well-written changelogs are organised by version, explain the impact of each change, and make it easy to review previous releases.
Example 1: Initial Release
Every project starts with an initial version. Keep the first entry focused on what users can do with the new release.
# Changelog
## 1.0.0 - 15 July 2026
### Added
- Initial public release.
- User authentication.
- Markdown editor with live preview.
- Export to HTML and PDF.
Best for
- New software projects
- Open-source repositories
- First public releases
Why this structure works
Readers can immediately see what the first version includes without searching through project documentation.
Example 2: Patch Release
Patch releases typically resolve bugs without introducing new features.
## 1.0.1 - 22 July 2026
### Fixed
- Corrected Markdown table rendering.
- Fixed file upload validation.
- Improved error messages during conversion.
Best for
- Bug fixes
- Performance improvements
- Minor corrections
Keeping fixes together helps users quickly identify whether an issue they experienced has been resolved.
Example 3: Minor Feature Release
Minor releases often introduce new functionality while remaining backwards compatible.
## 1.1.0 - 10 August 2026
### Added
- Support for Mermaid diagrams.
- Export to DOCX.
- Keyboard shortcuts.
### Improved
- Faster document rendering.
- Better mobile layout.
Readers can easily distinguish between new features and improvements.
Example 4: Major Release
Major releases usually include significant improvements or changes that may affect existing users.
## 2.0.0 - 5 January 2027
### Added
- Completely redesigned editor.
- Workspace management.
### Changed
- Updated navigation.
- Improved conversion engine.
### Breaking Changes
- Legacy API endpoints have been removed.
- Minimum supported browser version has changed.
Best for
- Major software updates
- Platform redesigns
- Significant architectural changes
Example 5: Security Update
Security releases should clearly explain what was addressed without exposing unnecessary technical details.
## 2.0.2 - 18 January 2027
### Security
- Improved session validation.
- Updated authentication dependencies.
- Resolved a vulnerability affecting file uploads.
Users should immediately recognise that this release contains important security improvements.
Example 6: Deprecated Features
When features are scheduled for removal, communicate that early.
## 2.1.0
### Deprecated
- Legacy export API.
- Classic editor mode.
These features will be removed in a future release. Please migrate to the newer alternatives.
Why this structure works
Deprecation notices give users time to update their workflows before support ends.
Example 7: Removed Features
Once deprecated features are removed, explain what changed and where users should go next.
## 3.0.0
### Removed
- Legacy authentication endpoints.
- Classic export engine.
### Migration
Update integrations to use the current authentication API before upgrading.
Migration guidance reduces confusion during major upgrades.
Example 8: API Changelog
Developer-facing APIs often require more technical detail than customer-facing software.
## API v2.4
### Added
- New search endpoint.
### Changed
- Pagination now supports cursor-based navigation.
### Fixed
- Improved validation for request parameters.
### Deprecated
- Offset-based pagination.
Best for
- REST APIs
- SDK releases
- Developer platforms
Example 9: Customer-Facing SaaS Release
Not every changelog is written for developers. Customer-facing products should focus on benefits rather than implementation details.
## September 2026
### New
- Share documents using secure public links.
- Automatic dark mode.
### Improved
- Faster search across workspaces.
- Better accessibility for keyboard users.
### Fixed
- Resolved occasional login issues on mobile devices.
Why this structure works
Customers care about what has improved for them, not which internal components were refactored.
A Changelog Should Tell the Story of Your Project
Over time, a changelog becomes more than a list of updates—it becomes the history of your project.
Someone returning after six months should be able to scan recent releases and quickly understand how the software has evolved without reading every commit or issue.
Writing clear, consistent entries from the beginning makes that history far more useful.
Write Changelog Entries That Help Users
A changelog shouldn't read like a list of Git commits.
Most people scanning a changelog want to know three things:
- What's new?
- Has anything changed that affects me?
- Should I update now?
Every entry should help answer those questions quickly.
Group Related Changes Together#
As projects grow, dozens of small updates can make a changelog difficult to read.
Instead of listing every individual change, group similar updates under a clear heading.
For example, instead of:
- Fixed login issue.
- Fixed session timeout.
- Fixed password reset.
- Fixed authentication redirect.
Write:
### Authentication
- Fixed occasional login failures.
- Improved session handling.
- Resolved password reset issues.
- Corrected authentication redirects after sign-in.
Grouping related changes makes large releases much easier to scan.
Explain the Impact, Not Just the Change#
A changelog is more useful when readers understand why an update matters.
Instead of:
Added export feature.
Write:
Added PDF export so documents can be shared without requiring Markdown support.
A little context helps users understand the benefit without reading additional documentation.
Keep Categories Consistent#
Using the same section names across every release makes changelogs predictable and easier to navigate.
A common structure includes:
| Category | When to use it |
|---|---|
| Added | New features and functionality |
| Changed | Updates to existing behaviour |
| Improved | Performance or usability enhancements |
| Deprecated | Features planned for removal |
| Removed | Features no longer available |
| Fixed | Bug fixes and corrections |
| Security | Security-related improvements |
Readers quickly learn where to look for the information that matters to them.
Make Breaking Changes Easy to Spot#
Breaking changes deserve their own section.
Don't hide them inside a long list of updates.
### Breaking Changes
- Legacy authentication endpoints have been removed.
- API clients must now send a Bearer token.
- Minimum supported PHP version is now 8.2.
Clear migration information helps developers upgrade with confidence.
Keep the Level of Detail Consistent#
One release shouldn't contain detailed explanations while the next uses only a few vague words.
Compare these examples:
Less helpful
- Fixed bugs.
- Improved performance.
- Updated dependencies.
More helpful
- Fixed incorrect table alignment in exported Markdown.
- Reduced document conversion time for large files.
- Updated dependencies to address compatibility and security improvements.
Consistent detail makes the changelog more useful over time.
Changelog vs Release Notes
These terms are often used interchangeably, but they serve different audiences.
| Changelog | Release Notes |
|---|---|
| Records changes between versions | Explains highlights of a release |
| Usually organised by version number | Often organised by features or improvements |
| Focuses on accuracy and completeness | Focuses on communication and user value |
| Common in developer documentation | Common in product announcements |
Many software projects publish both. A changelog documents every important change, while release notes highlight the updates users are most likely to care about.
Common Mistakes
Writing Entries That Are Too Vague#
Entries such as:
- Improved performance.
- Fixed issues.
- Updated system.
don't tell users what actually changed.
A short, specific explanation is far more helpful.
Including Every Internal Change#
Not every commit belongs in a public changelog.
Internal refactoring, temporary experiments, and development-only changes rarely help end users understand a release.
Focus on updates that affect how the software behaves or how people use it.
Mixing Different Versions Together#
Each release should have its own section.
Avoid adding new changes to older version entries after they've been published.
This keeps the project history accurate and easy to follow.
Forgetting Migration Instructions#
If users need to update configuration files, replace deprecated APIs, or change their workflow, explain that alongside the release.
Migration guidance can prevent unnecessary support requests.
Inconsistent Formatting#
Switching between different heading styles, date formats, or category names makes changelogs harder to scan.
Choose one format and use it consistently throughout the project.
Frequently Asked Questions
- 1
What's the difference between a changelog and Git history?
Git history records every commit made during development. A changelog summarises the changes that matter to users between released versions, making it much easier to understand how the project has evolved.
- 2
Should every release have a changelog entry?
Yes. Recording each release creates a complete version history and helps users identify when features, fixes, or breaking changes were introduced.
- 3
How detailed should a changelog be?
Include enough information for users to understand what changed and whether it affects them. Avoid listing every internal implementation detail unless it's relevant to developers using your project.
- 4
Should I include unreleased changes?
Many projects maintain an Unreleased section during development and move those entries into a versioned release when it's published. This helps teams keep track of upcoming changes before a release is finalised.
- 5
Should I delete old changelog entries?
No. Older entries provide valuable historical context and help users identify when features were introduced, changed, or removed. A changelog becomes more useful as it grows.