How to set up a changelog for a SaaS in an afternoon
To set up a changelog for a SaaS, create one public page where each release is a dated entry, newest first, with changes grouped under headings such as Added, Changed, Fixed and Removed. Write it for customers instead of copying commit messages, and flag anything that breaks existing behavior. You can host it as a markdown file, a page on your site, or GitHub Releases.
This guide follows the Keep a Changelog convention and GitHub's release documentation, both read on 14 November 2026. Where a step is our own suggestion, it says so.
What a changelog is for
The Keep a Changelog project defines a changelog as a curated, chronologically ordered list of notable changes for each version of a project. Its stated reason is to make it easier for users to see what changed between releases. For a SaaS the same logic applies, with one difference: your customers do not choose a version, so they find out about changes only when you tell them.
A changelog helps three groups. Existing customers learn what is new and what to retest. Prospects see whether the product is alive. Support gets a link to paste when someone asks "did you fix that?" If you run a public API, it also gives integrators a place to learn about deprecations before they break.
Pick a home
You have three realistic options for a small team.
| Option | Good for | Trade-off |
|---|---|---|
CHANGELOG.md in the repo, rendered on your site | Open-source or developer tools | Needs a build step to appear on your site |
A /changelog page on your own site | Most SaaS products | You maintain it by hand |
| GitHub Releases | Products with a public repo | Visible only on GitHub |
Keep a Changelog notes that GitHub Releases create a non-portable changelog that can only be displayed within GitHub, and that the releases page is arguably not very discoverable by end users compared with a conventional file such as CHANGELOG.md. If your customers are not on GitHub, a page on your own domain is the better home. If you build the site with Docusaurus, a post per release is a natural fit, and adding FAQ schema to a Docusaurus blog shows how that kind of setup works.
The format
Keep a Changelog lists these guiding principles: changelogs are for humans, there is an entry for every version, the same types of changes are grouped, versions and sections are linkable, the latest version comes first, the release date is displayed, and you say whether you follow Semantic Versioning. Its suggested change types are:
- Added for new features
- Changed for changes in existing functionality
- Deprecated for soon-to-be removed features
- Removed for features that are now gone
- Fixed for bug fixes
- Security for vulnerabilities
For dates it recommends the ISO format, such as 2026-11-14, because regional formats overlap in ambiguous ways. A small example entry:
## 2026-11-14
### Added
- CSV export on the Invoices page.
### Changed
- Webhook retries now stop after 24 hours instead of 72.
### Deprecated
- The `/v1/customers` endpoint. It will be removed on 2027-03-01. Use `/v2/customers`.
SaaS products rarely have version numbers customers care about, so date-based entries work well. That is our suggestion, and Keep a Changelog mentions that you should say whether you follow Semantic Versioning, so state your choice at the top of the page.
Seven steps to set it up
- Create the page or file today, with a one-paragraph intro that says how often you update it and how to subscribe.
- Add an
Unreleasedsection at the top. Keep a Changelog suggests it so people can see what to expect and so that at release time you can move its contents into a dated section. - Backfill only the changes customers noticed in the last few months. A short honest history beats a long invented one.
- Add a line to your release checklist: "write the changelog entry before merging." Ten minutes at release time is cheaper than reconstructing a month later.
- Write each line from the customer's point of view. "Fixed double charge when a card is retried" is useful. "Refactor billing service" is not.
- Link out to docs or a longer post for anything that needs explanation.
- Offer a way to follow along: an RSS or Atom feed, an email, or a link in your product. Pick one.
Do not paste your commit log
Keep a Changelog is blunt about this: using commit log diffs as changelogs is a bad idea because they are full of noise, such as merge commits and obscure titles. A commit documents a step in the code. A changelog entry documents a noteworthy difference, often across multiple commits.
It lists other failure modes too. Ignoring deprecations is one: when something will break, it should be painfully clear, and at minimum you should list deprecations, removals and breaking changes. Inconsistency is another. A changelog that mentions only some changes can be as dangerous as none, because readers assume it is the single source of truth.
Using GitHub Releases
If your product has a public repository, GitHub's documentation on managing releases describes the flow. You choose or create a tag, write a title and description, and can click Generate release notes to produce notes automatically. A release can be marked as a pre-release, which signals that it is not ready for production. The gh release create command does the same from the terminal. Generated notes are a starting point, so edit them into customer language before you publish.
Keeping it up to date
A changelog that goes quiet for three months looks like an abandoned product. Our habit suggestion: put a standing five-minute task on your Friday list to add entries for anything that shipped. If your product exposes an API, MCP server vs REST API for a SaaS covers interface choices where deprecation notices matter most.
Frequently asked questions
Should a SaaS changelog use version numbers?
Not necessarily. Customers on a hosted product do not pick versions, so dates often work better. If you publish an API or an SDK, version numbers help integrators, and Keep a Changelog recommends stating whether you follow Semantic Versioning.
How often should I update a changelog?
Update it whenever you ship something a customer could notice. For most small teams that means weekly or at each release. The key is consistency, since an incomplete changelog can mislead readers.
What belongs in a changelog and what does not?
Include new features, behavior changes, deprecations, removals, bug fixes customers could see, and security fixes. Leave out internal refactors and dependency bumps unless they affect users.
Is GitHub Releases enough as a changelog?
It can be, if your customers use GitHub. For a typical SaaS with non-developer customers, a page on your own domain is easier to find and does not depend on a third-party site.