Changelog Markdown Template
Maintain an Unreleased section and versioned Added, Changed, Deprecated, Removed, Fixed, and Security entries with migration notes.
# Changelog
All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning policy: [describe or link].
## [Unreleased]
### Added
- [User-visible addition]
### Changed
- [Behavior change]
### Deprecated
- [Feature scheduled for removal and recommended replacement]
### Removed
- [Removed capability]
### Fixed
- [User-visible fix]
### Security
- [Security-relevant change with an appropriate advisory link]
### Migration notes
- **Who is affected:** [Users or integrations]
- **Required action:** [Ordered upgrade steps]
- **Rollback:** [Verified rollback option, if available]
## [X.Y.Z] - YYYY-MM-DD
### Added
- [Released addition]
### Changed
- **Breaking:** [Changed behavior]. Migrate by [verified instruction].
### Fixed
- [Released fix]
[Unreleased]: https://example.com/example-org/example-project/compare/vX.Y.Z...HEAD
[X.Y.Z]: https://example.com/example-org/example-project/compare/vPREVIOUS...vX.Y.Z
Changelog
All notable changes to this project are documented here. The format follows Keep a Changelog; versioning policy: [describe or link].
Unreleased
Added
- [User-visible addition]
Changed
- [Behavior change]
Deprecated
- [Feature scheduled for removal and recommended replacement]
Removed
- [Removed capability]
Fixed
- [User-visible fix]
Security
- [Security-relevant change with an appropriate advisory link]
Migration notes
- Who is affected: [Users or integrations]
- Required action: [Ordered upgrade steps]
- Rollback: [Verified rollback option, if available]
X.Y.Z - YYYY-MM-DD
Added
- [Released addition]
Changed
- Breaking: [Changed behavior]. Migrate by [verified instruction].
Fixed
- [Released fix]
When to use this template
Use this for a human-readable record of notable product or library changes. It is useful before each release and when users need upgrade context beyond commit messages.
Section guide
- Unreleased
- Collect notable changes as they land.
- Version entries
- Group released changes by standard Keep a Changelog categories.
- Migration and comparison links
- Help readers assess and navigate upgrades.
How to use this template
- 1
Copy the Markdown
Click the Copy button above to put the full template on your clipboard.
- 2
Paste into your editor
Paste into the mdkit editor, a repository, a notes app, or another Markdown editor. Check tables and task lists in your target renderer because Markdown support varies.
- 3
Fill in your content
Replace bracketed examples with verified information, adapt fields to your context, and remove sections that do not apply.
- 4
Check before you use it
- A changelog is curated for users; it should not be an automatic dump of every commit.
- Version numbers, tags, repository URLs, and release dates must match the real project.
Template details
What it solves
A structured changelog lets users see what changed, identify breaking behavior, and find migration instructions before upgrading.
Key features
- Unreleased section for work not yet shipped
- Keep a Changelog change categories
- Breaking-change and migration guidance
- Placeholder links for version comparisons
Pro tips
- >Write entries from the user's perspective rather than repeating commit subjects.
- >Call out breaking changes before routine fixes.
- >Move only shipped entries from Unreleased into a verified version and date.
Useful Markdown tools
Start in the Markdown editor, then use a relevant tool when you need to format or export the finished document.
Related templates
Project README
Document a software project with prerequisites, installation, usage, configuration, testing, support, contribution, and license sections.
API Documentation
Describe API authentication, endpoints, requests, responses, errors, pagination, and rate limits with copyable Markdown examples.
Project Post-Mortem
Review a completed project against its plan using evidence, impact, contributing factors, lessons, and owned follow-up actions.