What Is a Changelog?

A changelog is a curated, reverse-chronological record of notable changes to a product or project—usually grouped by version (or date) and categorized so technical readers can see what was added, changed, fixed, or removed.

It is the technical ledger; customer-facing release notes summarize user impact in plainer language. Many teams keep both. See release notes vs. changelog for when each one fits.

When a changelog is the right artifact

• Developers, integrators, and power users need a precise history (API, SDK, infrastructure).
• Compliance / audit needs a durable trail of what changed when.
• Open source / multi-contributor projects need a shared history beyond raw commits.
• Continuous delivery teams still want a readable rollup—not every commit dump.

Prefer customer release notes (or both) when the goal is adoption, benefit language, or GTM alignment. Audience routing → audiences.

Core components

Keep a Changelog categories

A widely used structure (Keep a Changelog) groups entries under:

• Added — new capabilities
• Changed — changes in existing behavior
• Deprecated — soon-to-be removed; pair with lead time → breaking changes
• Removed — now removed
• Fixed — bug fixes
• Security — vulnerability fixes

Conventions of a well-kept changelog

The Keep a Changelog convention goes beyond categories. Its core rules:

• Newest first. The latest release sits at the top.
• One entry per version, with a date. Use ISO format (2026-09-15) so dates read the same everywhere.
• An @@PROTECT2@@ section at the top collects changes that are merged but not shipped yet. At release time you rename it to the new version, which avoids a last-minute scramble.
• Linkable versions. Each version heading should link to its diff, tag, or release page so readers can drill down.
• Say whether you follow semantic versioning. SemVer (MAJOR.MINOR.PATCH) tells integrators that a MAJOR bump may break things.
• Mark pulled releases as @@PROTECT4@@ instead of deleting them, so the history stays honest.

[Unreleased]
Added
- Bulk-archive for projects
[2.4.0] - 2026-09-15
Added
- Webhook retries with exponential backoff for failed deliveries
Fixed
- Dashboard filter no longer resets when switching saved views
Deprecated
- Legacy v1 export endpoint (removal planned for 2026-12-01; see migration guide)
[2.3.1] - 2026-09-02 [YANKED]

Where a changelog lives

Pick one canonical location per audience and link to it from the others, rather than maintaining several copies that drift.

SaaS continuous-delivery caveats

• Not every deploy needs a public row — Batch low-severity fixes; call out breaks and deprecations immediately.
• Version vs calendar — Some products version weekly trains; others label by date. Pick one scheme and stick to it.
• Auto-from-git is a draft — Generators help; humans still filter noise and write integrator-facing clarity → automation.
• Two tracks are fine — Technical changelog + customer release notes. Do not force one document to serve both audiences poorly.

Writing hygiene (changelog-specific)

• Be precise enough for debugging and upgrades; link docs or PRs when useful.
• Avoid empty entries (“miscellaneous improvements”) as the only line for a release.
• If an entry affects customers who are not engineers, also ship a release note—or say so and link it.

Customer-facing wording patterns → how to write.

How to start (or fix) a changelog

Skip the blank file: copy a ready-made Markdown and customer-facing version from our changelog template.

1. Choose a scheme. Pick semantic versions or dated releases, state it at the top of the changelog, and stick to it.
2. Start from today. You don't need to back-fill years of history. Begin with the current version and add an [Unreleased] section.
3. Capture changes where they happen. Ask for a one-line, user-visible summary on each pull request, or use a commit convention such as Conventional Commits (feat:, fix:, BREAKING CHANGE:) so tools can sort entries into categories.
4. Generate the draft, then edit it. Tooling can assemble the list; a person removes noise, merges duplicates, and rewrites anything unclear (how to automate release notes).
5. Publish on every release, and link each customer-visible entry to its release note where one exists.

FAQ

Is a changelog the same as release notes?

No. A changelog is the technical record; release notes are the user-impact narrative. Full comparison → vs changelog.

Do we need semantic versioning?

Helpful when compatibility matters (APIs, libraries). Product-led SaaS UIs sometimes use dated releases instead—consistency matters more than dogma.

Should every commit appear?

No. Notable, user- or integrator-visible changes only. Dumping every commit trains people to ignore the file.

Where do deprecations go?

Under Deprecated (and later Removed), with dates and migration paths. Playbook → breaking changes.

What should the changelog file be called?

CHANGELOG.md at the root of the repository is the most widely recognized convention, and it's the name Keep a Changelog recommends. For product changelogs published on the web, /changelog or /releases are the paths readers most often expect.

Keep the ledger readable

Use clear versions or dates, honest categories, and CD-aware batching. Pair with release notes when adoption is the goal. LaunchNotes can publish a customer-facing updates page alongside a technical track. Worth a look if your “changelog” is still a raw commit export nobody trusts.