What Is a Changelog?

A changelog is a chronological record of all notable changes made to a software project. It serves as a public-facing history of what was added, changed, fixed, or removed in each release. Unlike commit logs or pull request lists, which are written for developers during the development process, a changelog is curated for a broader audience -- users, customers, stakeholders, and anyone who needs to understand how the software has evolved over time.

Changelogs have been a convention in open-source software for decades, often maintained as a CHANGELOG.md file in the project root. In the SaaS world, changelogs have expanded beyond a single file to become hosted pages, email digests, and multi-channel communication systems. Regardless of format, the core purpose remains the same: to answer the question "what changed and when?"

Changelog vs. Release Notes: What Is the Difference?

The terms "changelog" and "release notes" are often used interchangeably, but they refer to subtly different things.

A changelog is the complete, cumulative record. It contains every notable change across every release, ordered by date or version number. Think of it as the full history. When someone visits your changelog page, they can scroll through months or years of product evolution.

Release notes refer to the documentation for a single release. They describe what was included in one specific version or deployment. Release notes are a snapshot; the changelog is the collection of all snapshots.

In practice, the distinction matters less than the outcome. Whether you call it a changelog or release notes, the goal is the same: inform your audience about what changed. What matters is that the content is clear, timely, and reaches the people who need it.

Changelog Formats and Standards

The Keep a Changelog Standard

The most widely adopted standard for structuring changelogs is Keep a Changelog, created by Olivier Lacan. It defines a simple, human-readable format with these categories:

• Added -- for new features
• Changed -- for changes in existing functionality
• Deprecated -- for features that will be removed in upcoming releases
• Removed -- for features that have been removed
• Fixed -- for bug fixes
• Security -- for vulnerability patches

Each release gets a section with the version number and date, followed by the categorized entries. The format is intentionally simple -- it is a Markdown file that any developer can read, edit, and maintain. The Keep a Changelog standard is widely used in open-source projects and has become the de facto baseline for how changelogs should be structured.

Semantic Versioning

Changelogs are closely tied to semantic versioning (SemVer), the convention where version numbers follow the format MAJOR.MINOR.PATCH. A major version bump signals breaking changes. A minor bump signals new features. A patch bump signals bug fixes. When a changelog follows SemVer, users can quickly gauge the significance of a release by looking at the version number alone.

For SaaS products that deploy continuously, strict version numbering is less common. Many teams use dates instead of version numbers, or simply list changes in reverse chronological order without formal versioning. The important thing is that each entry is timestamped and clearly delineated from the others.

Conventional Commits

The Conventional Commits specification provides a structured format for commit messages: feat: add user export, fix: resolve login timeout, docs: update API reference. Tools like conventional-changelog and release-please parse these prefixes to automatically generate changelog entries. This approach ensures consistency but produces developer-oriented output that often needs rewriting before it is suitable for a user-facing changelog.

Where to Host Your Changelog

The best location for your changelog depends on your audience and product type.

A dedicated changelog page on your website is the most common approach for SaaS products. A page at yourproduct.com/changelog or docs.yourproduct.com/changelog gives users a permanent, searchable URL to check for updates. It also serves as a trust signal -- prospective customers visit the changelog to verify that the product is actively maintained.

GitHub Releases are the standard for open-source projects. Each tagged release on GitHub can include release notes in Markdown. The advantage is that the changelog lives where the code lives, and contributors can find it without leaving GitHub. The disadvantage is that non-technical users rarely visit GitHub.

Documentation sites sometimes include a changelog section. This makes sense when the changelog is tightly coupled with API documentation or developer docs. Users reading the docs can check what has changed without navigating to a separate site.

In-app changelog widgets display recent changes inside the product itself. These have the highest visibility because users encounter them during their normal workflow. Some products use a "what's new" badge or a notification bell that links to recent changelog entries.

A CHANGELOG.md file in the repository root remains a staple for libraries, frameworks, and open-source tools. It is the first place a developer looks when evaluating whether to upgrade a dependency.

Best Practices

Maintaining a useful changelog is not complicated, but it requires discipline. Here are the practices that separate helpful changelogs from abandoned ones.

• Update it with every release. The number one reason changelogs fail is inconsistency. If you skip a few releases, the effort to catch up compounds and the changelog gets abandoned. Treat the changelog update as part of your release process, not a separate task to do later.
• Write for humans, not machines. A changelog entry that says bump lodash from 4.17.20 to 4.17.21 is noise. A changelog should describe changes that matter to the people reading it. Dependency bumps, minor refactors, and internal tooling changes can be omitted unless they affect behavior. For a deeper look at this problem, read why your changelog is costing you users.
• Group and categorize consistently. Use the same categories every time -- whether you follow Keep a Changelog, use your own taxonomy, or simply group by "New," "Improved," and "Fixed." Consistency makes the changelog scannable and predictable.
• Include dates. Every changelog entry should be dated. Users need to know when a change was made, especially when troubleshooting issues or deciding whether to upgrade. A changelog without dates is a timeline without a time axis.
• Link to details when available. If a changelog entry describes a significant new feature, link to the documentation page, blog post, or help article that explains it in depth. The changelog entry should be concise; the linked resource can be comprehensive.
• Do not overload it. Not every commit needs a changelog entry. The goal is to document notable changes -- the ones that users, developers, or stakeholders would want to know about. Internal refactors that do not change behavior should be left out.

Common Mistakes

The same patterns derail changelogs across organizations of every size.

Using commit messages as changelog entries. Auto-generating a changelog directly from git commits produces output like "fix typo," "WIP," "merge branch main," and "address review feedback." These messages were written for teammates during development, not for an audience reading the changelog weeks later. A changelog needs curation.

Letting it go stale. A changelog that has not been updated in three months tells users the product is either dead or the team does not care about communication. Both interpretations are bad. Inconsistency is worse than having no changelog at all, because a stale changelog sets an expectation and then breaks it.

Making it hard to find. If users have to dig through your documentation navigation to find the changelog, most of them will not bother. Put it in your main navigation, link to it from your footer, and reference it in your product update emails. A changelog that nobody can find serves nobody.

Only publishing on one channel. A changelog page is a pull mechanism -- it only works if users visit it. Most will not. Multi-channel distribution -- email, in-app, social, Slack -- turns your changelog from a passive archive into an active communication tool. This is the difference between "we documented it" and "our users actually know about it."

Omitting breaking changes. Breaking changes must always be called out explicitly. If an API endpoint is deprecated, if a behavior changes, if a migration is required -- these need to be prominently flagged. Burying breaking changes in a list of minor fixes is a fast path to angry users and overloaded support queues.

Automating Your Changelog

Maintaining a changelog manually works when you ship once a month. When you ship daily, it becomes a bottleneck -- either someone spends time writing entries for every merge, or the changelog falls behind. This is why more teams are turning to automation.

The simplest form of automation is commit-based generation. Tools like release-please parse conventional commit messages and create structured changelog entries. This eliminates the writing step but produces technical output that is best suited for developer audiences.

AI-powered changelog tools go further. Rather than parsing commit messages into a template, they read the full context of each change -- the code diff, the pull request description, the linked issue -- and generate changelog entries written in natural language, tailored to the intended audience.

Recaip takes this approach to its logical conclusion. It connects to your GitHub repository, listens for merged pull requests, and generates a complete changelog entry within seconds. But it does not stop at the changelog. Recaip also generates a social media post, an email draft, an in-app announcement, and a stakeholder digest -- all from the same merge event. You can review each draft before publishing, or set individual channels to auto-publish once you trust the quality. The result is a changelog that stays current without anyone on your team maintaining it. For a practical walkthrough, see how to automate release notes with AI.