Keep a Changelog

Best Practice: Keep a Changelog

Keep a Changelog, created by Olivier Lacan, is a simple convention for writing changelogs that humans actually want to read. A changelog is a curated, chronologically ordered list of notable changes for each released version of a project. The convention recommends a CHANGELOG.md file, an Unreleased section at the top, and grouping entries under standard headings: Added, Changed, Deprecated, Removed, Fixed, and Security. It pairs naturally with Semantic Versioning, where the version number itself signals whether a release is a breaking, feature, or fix release. The guiding principle is that a changelog is for people, not machines: it summarizes the impact of changes in clear language rather than reproducing raw commit history. For modernization, a disciplined changelog gives downstream teams the exact information they need to plan upgrades, sequence dependency updates, and assess migration impact before they pull a new version.

Step-by-Step Implementation Guidance

1. Create a CHANGELOG.md at the repository root.
2. Keep an Unreleased section at the top to collect upcoming changes.
3. Group every change under Added, Changed, Deprecated, Removed, Fixed, or Security.
4. Write entries for humans: describe the impact, not just the commit message.
5. On release, move Unreleased entries under a new version heading with a date.
6. Follow Semantic Versioning so the version number signals the kind of change.
7. Call out breaking changes and deprecations prominently.

Common Mistakes Teams Make When Ignoring This Practice

• Dumping raw git logs that no human can parse.
• Burying breaking changes where consumers miss them.
• Inconsistent or missing dates and version headings.
• Mixing change types so readers cannot scan by category.
• No Unreleased section, so the changelog is always behind.

Tools and Techniques That Support This Practice

• The Keep a Changelog format and CHANGELOG.md convention.
• Semantic Versioning for meaningful version numbers.
• Release tooling such as release-please and changesets that generate sections.
• Conventional Commits as an input to automated changelog generation.

How This Practice Applies to Different Migration Types

• Cloud Migration: Record infrastructure and configuration changes so operators know what shifted between releases.
• Database Migration: Log schema changes and deprecations so dependent services plan upgrades.
• SaaS Migration: Publish clear release notes so customers see new, changed, and removed behavior.
• Codebase Migration: Flag breaking API changes and removals to guide consumers through the transition.

Checklist

• A CHANGELOG.md exists at the repo root.
• An Unreleased section collects pending changes.
• Entries are grouped by standard change types.
• Each release has a version and a date.
• Breaking changes are clearly highlighted.
• Semantic Versioning is followed.
• Entries describe impact for human readers.