What does a changelog contain?
A changelog is a running list, newest first, of the changes that matter to the people who use a product. It lives at a stable address, such as a public web page, a CHANGELOG.md file in a repository, or an in-app feed. Each entry carries three things: when the change shipped (a date, a version number, or both), what kind of change it is, and a short description written for the reader rather than for the engineer who built it.
The most common entry types come from the Keep a Changelog format: Added, Changed, Deprecated, Removed, Fixed, and Security. Teams that ship versioned software usually pair those groups with semantic versioning, so a reader can tell a bug fix from a breaking change at a glance. SaaS teams that deploy continuously tend to drop version numbers and organize entries by date instead.
A changelog is not a commit log. Commit messages describe every code change, including refactors and typo fixes, in the order developers made them. A changelog is curated. Someone decides which changes a user would care about and rewrites them in plain language. That editorial step is what turns raw history into a document people actually read.
Why does a changelog matter for SaaS teams?
Without a changelog, product changes reach customers by accident. A user notices a moved button, assumes something broke, and opens a support ticket. Another user never discovers a feature they asked for six months ago, because nobody told them it shipped. Both outcomes cost money: the first in support time, the second in wasted engineering effort and weaker feature adoption.
A changelog fixes this by creating one canonical answer to the question "what changed?" Support agents link to it instead of explaining the same change repeatedly. Customer success managers open renewal conversations with a list of what the customer gained this year. Sales prospects who are evaluating the product can see that it is actively maintained, which is a trust signal no marketing page can fake.
Internally, a changelog forces a habit of finishing work properly. If every shipped change needs a sentence a customer can understand, engineers and product managers have to agree on what the change is for. Teams that keep an internal changelog alongside the public one also give sales, support, and marketing an early heads-up before customers see anything.
Changelog examples
Changelogs take different shapes depending on who reads them.
- A CHANGELOG.md in a repository. Open source libraries keep a Markdown file at the project root, grouped by version with an Unreleased section on top. Developers read it before upgrading a dependency.
- A developer platform changelog. API providers publish a dated list of endpoint changes, new parameters, and deprecations, often with links to migration guides. The audience is technical, so entries are precise about backward compatibility.
- A SaaS product changelog page. Business software companies run a page on their own domain with short posts, a screenshot or short video each, and labels such as New, Improved, and Fixed. The reader is an end user, so the copy explains benefits rather than implementation.
- An in-app changelog feed. The same posts appear inside the product through a changelog widget, typically a bell icon or a sidebar panel, so users see updates at the moment they are already working.
You can compare full templates for each style in our changelog template guide.
How to write a good changelog
The rules below apply whether you publish a Markdown file or a branded web page.
- Write for the reader, not the author. Say what the user can now do, or what stopped going wrong. Avoid ticket numbers and internal code names in public entries.
- Lead with the most important change. Readers skim. Put the headline feature first and group minor fixes at the bottom of the entry.
- Label every change by type. Consistent labels such as Added, Changed, Fixed, and Removed let readers filter for what affects them.
- Date every entry, and version it if you ship versions. A change without a date is impossible to reference in a support conversation.
- Keep one entry per release, not per commit. Batch small changes into a single dated entry so the log stays readable.
- Call out breaking changes and deprecations loudly. Use a dedicated label and link to the migration path. This is the one place where over-communicating is correct.
- Publish on a predictable cadence. Weekly or biweekly entries train users to check back. Long silences make the product look abandoned, even when it is not. Pick a rhythm you can keep.
- Distribute it. A page nobody visits is a filing cabinet. Push entries to an in-app feed, an email digest, and Slack so the changelog reaches people where they already are.
Changelog vs release notes vs product updates
These three terms overlap, and teams often use them interchangeably. The differences are about scope and tone.
Changelog is the complete, ongoing record. It is terse, structured, and includes minor fixes. Release notes describe one specific release in more depth, with context on why the change was made and how to use it. A changelog can be assembled from many release notes, but release notes are usually longer and more narrative. Product updates is the broadest term. It covers any customer-facing communication about the product, including announcements, launch emails, and blog posts, and it is the language marketers tend to prefer. Our post on changelog vs release notes goes deeper on when to use each.
Common changelog mistakes
- Pasting commit messages or Jira ticket titles straight into public entries.
- Skipping small fixes because they seem unimportant. Someone reported that bug and is waiting to hear it is fixed.
- Burying breaking changes in the middle of a long entry.
- Publishing to a page and never linking to it from the product, the docs, or the help center.
- Letting the log go stale for months, which signals the product is not moving.
How AnnounceKit handles changelog
AnnounceKit publishes your changelog as a page on your own domain and mirrors every post inside your product through more than ten in-app widget display modes. Posts can be segmented so each user sees only the changes relevant to their plan or role, and the same posts go out as email digests and Slack messages without extra work. Feature requests with voting and Jira sync, plus NPS surveys, sit alongside the changelog so feedback and announcements share one workspace. AI post generation drafts entries from your notes, and an official MCP server is available for AI agents. Pricing is flat per project from $79 per month, with a 15-day free trial.