What is a changelog? A plain-English definition (with examples)

A changelog is a chronological, dated record of the changes made to a product, written for the people who use it. Each entry says what changed, when, and — when it matters — what to do about it. That's the whole idea. Everything else (formats, tags, version numbers, tooling) is detail on top of those three facts.

The word is literally "a log of changes", and it shows up under many names: release notes, "What's new", product updates, a CHANGELOG.md file in a repository, a news feed on a website. The names differ more than the thing does. If it's a dated list of changes, ordered newest-first, meant to be read by someone other than its author — it's a changelog.

What a changelog looks like

Here's a representative slice of one:

2026-07-21 — New: import your GitHub Releases

Point us at a repo URL and your published releases become
changelog entries. Drafts are skipped; pre-releases are marked.

2026-07-14 — Fix: you no longer get signed out when your laptop sleeps

If the app "randomly" logged you out this month, this was why.
Sessions now survive suspend/resume.

2026-07-08 — Breaking: API v1 date fields switch to ISO 8601 on Sept 1

Timestamps in list endpoints change from Unix seconds to ISO 8601
strings. Update parsers before September 1. Details and examples
in the entry below.

Notice what makes this a changelog rather than a diary: every entry is dated, leads with the change (not the effort behind it), names user-visible symptoms ("randomly logged out"), and flags the one entry that demands action with a loud Breaking: prefix. For a tour of real products that do this well — Slack, Stripe, VS Code, Linear — see our changelog examples guide.

What a changelog is not

The definition gets clearer at its edges. Four neighbors it's commonly confused with:

• A commit log. git log is a record for the people who build the product; a changelog is for the people who use it. Commits say "refactored session middleware"; the changelog says "you stay signed in after your laptop sleeps". You can generate a draft changelog from commits, but publishing raw commits as your changelog is the single most common way to have one nobody reads.
• Release notes. Nearly the same thing — release notes are the per-release document; the changelog is the running timeline they accumulate into. The distinction and a one-source workflow are covered in changelog vs release notes.
• A roadmap. A roadmap is promises about the future; a changelog is proof about the past. Never mix tenses: "Coming soon" doesn't belong in a changelog. More in roadmap vs changelog.
• A status page. A status page answers "is it working right now?"; a changelog answers "what has changed over time?". Different clocks, different infrastructure — see status page vs changelog.

Where changelogs come from

The practice is older than the word's current popularity. Unix and GNU projects shipped CHANGES and ChangeLog files alongside source code for decades — GNU coding standards formalized a ChangeLog format in the 1980s. The modern convention most developers know is Keep a Changelog (2014), which standardized the CHANGELOG.md file: newest release first, categories like Added / Changed / Fixed / Removed, and an Unreleased section at the top. We cover that format in detail in the Keep a Changelog format, explained.

Meanwhile SaaS products, which release continuously and rarely have version numbers users care about, evolved the dated stream style instead: a public "What's new" page with entries by date rather than by version. Both styles are changelogs; which one fits depends on whether people build against versioned interfaces of yours (see CalVer vs SemVer and semver in plain English).

Why products keep one

• It answers the support question before it's asked. "Did something change? The app looks different" is the opening line of half of all support threads. A changelog is the canonical link to answer it.
• It's the cheapest trust signal you can publish. Evaluators deciding whether to adopt your product look for a pulse. A changelog with steady, recent, honest entries reads as "actively maintained by people who tell the truth" — a cadence you can sustain matters more than volume.
• It's the upgrade channel. For libraries and APIs, the changelog is where "is it safe to update?" gets answered — which is why breaking changes and API deprecations have their own craft.
• It closes the loop with the people who reported bugs. "Fixed: the export that failed on files over 10 MB" tells the person who hit that bug that you heard them. Silent fixes waste the goodwill you already earned by fixing them.
• Future you needs it. "When did we change the pricing page?" is answerable in seconds with a changelog and in an afternoon of git archaeology without one. Teams often keep an internal changelog for exactly this.

What goes in one (and what stays out)

In: anything a user could notice or must act on. New features, behavior changes, fixes to symptoms users saw, deprecations with dates, security fixes, price/policy changes.

Out: refactors invisible to users, internal tooling, typo-level commits, and hype. If a week's work produced nothing user-visible, batch it or skip it — a changelog earns trust by being true, not by being busy. Phrasing rules, tags, and good-vs-bad examples are in how to write a changelog; if your audience isn't technical, see release notes for non-technical users; if you want skeletons to copy, release notes templates.

Where changelogs live

• A CHANGELOG.md file in the repository — canonical for libraries and CLIs; greppable, ships with the code (open source changelogs).
• GitHub Releases — notifications and Atom feeds for free, but platform-bound (same guide covers the trade-off).
• A hosted public page — linkable, indexable, works for products whose users never see a repository. This is what Wakelog provides.
• In-app "What's new" surfaces — a widget or popover that meets active users where they already are (in-app what's-new widgets).
• Email digests — the only channel that reaches people who stopped logging in (product update emails).

These aren't competitors; mature setups pick one canonical home and mirror to the rest.

How to start one today

1. Write the last three changes you shipped, dated, one line each, phrased as what a user would notice. That's a changelog. It took ten minutes.
2. Put it somewhere linkable — a CHANGELOG.md, a page, a hosted changelog. The test: can support paste one URL that answers "what changed?"
3. Wire it into your release flow so updating it isn't a separate chore — post from your release script, or mirror your GitHub/GitLab releases automatically. Changelogs die of friction, not of bad intentions.

Where Wakelog fits

Wakelog is a free hosted changelog: signup is username+password (no email), you get a public page with RSS and JSON feeds, an embeddable widget, a README badge, and an API/CLI so your deploy script — or your CI — can post entries. If you already have a CHANGELOG.md or GitHub Releases, paste or point us at it to see it as a hosted page in seconds, and export back to markdown anytime. No lock-in, no branding ransom.

Start your changelog free   Next: how to write a changelog →

Related guides

• How to write a changelog (with examples)
  Structure, tags, cadence, good vs bad entries, and automation — everything you need to keep a changelog people actually read.
• Changelog vs release notes: what’s the difference?
  They overlap, but they’re not the same document. When you need each — and how to avoid writing everything twice.
• The changelog field guide: how to announce anything you ship
  One hundred guides is a library, not an answer. This is the lookup table: match what you’re shipping, who receives it, and where they’ll read it — and read only the two or three guides that cover exactly that.

Last updated 2026-07-27 · All guides