Every SaaS team ships changes. Few get credit for them. Customers miss new features, prospects assume the product is static, and the work that would make the best marketing story, steady improvement, stays invisible inside a release branch.
A public changelog fixes that. Done well, it is a running, dated record of what got better, written for users and pushed to where they already are. This playbook covers why it works, how often to publish, how to write entries people actually read, and how to distribute them.
Why a changelog is a marketing asset
Linear, which has published a changelog since its early days, laid out the case in a post titled 'Startups write changelogs'. Its argument is that a changelog does several jobs at once:
- Momentum. A dated list of weekly improvements is proof that the product is alive, which matters a lot to a buyer betting on a young vendor.
- Early adopters. People who chose you early want to see their feedback turn into shipped work.
- Culture. Writing up what shipped every week reinforces a team habit of finishing things.
- Marketing raw material. Each entry is a ready-made social post, newsletter item, or sales talking point.
- Recruiting and investors. Candidates and investors read changelogs to judge how fast a team executes.
There is a search benefit too. Vercel gives each changelog entry its own page and URL, so a specific update can be linked, shared, and found on its own rather than buried in a long scrolling list.
Pick a cadence you can keep
The single most important property of a marketing changelog is that it keeps arriving. A changelog whose latest entry is four months old sends the opposite of the intended signal.
Linear recommends a weekly or bi-weekly cadence and published more than 50 changelogs in its first 12 months. incident.io went further: in a post on four years of weekly changelogs, it describes writing a customer update every week as 'held sacred', with more than 200 published and two years without missing a week. When a week is unusually busy, it publishes a bonus edition rather than skipping detail.
| Cadence | Works well for | Watch out for |
|---|---|---|
| Per release, as it ships | Teams shipping many independent changes daily | Entries too thin to read; noisy for email |
| Weekly | Most startups shipping continuously | Needs an owner and a fixed deadline |
| Bi-weekly | Smaller teams or slower release cycles | Easy to slip into monthly |
| Monthly roundup | Customer-facing digest on top of a faster log | Too slow on its own to signal momentum |
A common pattern is to combine two: a fast public log on the site, plus a less frequent digest by email. incident.io describes moving to exactly this, adding less frequent customer changelogs that cover several weeks of work.
Choose a format readers can scan
The Keep a Changelog project, written mainly for open-source release notes, still has the best short summary of format principles: changelogs are for humans, not machines; the latest version comes first; every entry has a date; similar changes are grouped together; and entries are linkable. It groups changes into Added, Changed, Deprecated, Removed, Fixed, and Security.
Product changelogs usually simplify that into fewer, friendlier tags. Linear's advice is to feature one to three larger changes and collect the small fixes in one section, and its current changelog follows that shape: a headline feature with images or video, then Improvements and Fixes lists. Our own changelog uses four tags: New, Improved, Fixed, and Security.
- One headline per entry. Lead with the most valuable change, not the first one merged.
- A short summary under it. Two or three sentences on who it helps and what they can now do.
- A visual for anything users will see. A screenshot or a 20 to 60 second clip.
- A grouped list for the rest. Small improvements and fixes, one line each.
- A link to the docs. Every new feature should point to a guide on how to use it.
Write benefit-led titles
incident.io's guidance is to frame each change around what customers can now do, not how it was implemented. Titles are where this matters most, because the title is what shows up in an email subject, a social post, or an RSS reader.
| Engineering-led title | Benefit-led title |
|---|---|
| Added CSV export endpoint | Export any report to CSV in one click |
| Refactored permissions model | Give contractors view-only access to a single project |
| Search indexing improvements | Search now finds results inside attachments |
| Fixed timezone bug in scheduler | Scheduled sends now go out in each recipient's time zone |
Who writes it matters. Linear notes that usually the person who built the feature also writes the changelog entry. incident.io has engineers write drafts too, and trains them in customer-friendly copywriting, with design and final reviews before publishing. Builders know the details; an editor makes sure the benefit comes first.
Show the change, don't just describe it
A sentence about a new feature is easy to skim past. A short clip of it working is not. Visuals also make each entry reusable: the same clip works on social, in the email digest, and inside the product.
- Use a clean screenshot with the new element highlighted. Our free screenshot beautifier adds padding, a background, and a window frame in the browser.
- For workflows, record a short walkthrough rather than a static image. Steperly's walkthrough video maker turns a recording into a polished, narrated video, and AI voiceover adds narration without recording your own voice.
- Link the entry to a step-by-step guide so interested users can go from 'that looks useful' to actually using it.
Distribute every update
A changelog page alone reaches only people who already go looking. Linear's original setup published entries on its website, shared them on Twitter with screenshots and demos, sent them to a newsletter, and showed them in-app during onboarding. incident.io started with an RSS feed that customers subscribed to in their Slack channels.
| Channel | What to send | Notes |
|---|---|---|
| Changelog page | Every entry, dated and linkable | The canonical home; give big entries their own URL |
| RSS feed | Every entry | Lets customers pipe updates into Slack or a reader |
| A digest of the most useful changes | Weekly or monthly; benefit-led subject line | |
| In-app | Changes relevant to the current user | A small 'What's new' badge, not a blocking modal |
| Social | One headline change with a clip | A clip shows the change before anyone clicks |
| Sales and success | Changes customers or prospects asked for | Close the loop with the person who requested it |
That last row is the highest-leverage one. incident.io connects its changelog process to its CRM so account teams hear when a feature a customer asked for ships. A personal 'you asked, we built it' message does more for retention than any broadcast.
How to tell if it's working
A changelog is cheap to run, but it still deserves a few numbers so you know which parts to keep. None of these need new tooling:
- Feature adoption after an announcement. Compare usage of a new feature in the week after the entry and email go out with the week before.
- Email digest engagement. Opens matter less than clicks through to the entry or the linked guide.
- Changelog visits from prospects. If your analytics can separate logged-out visitors, check how many evaluators read the changelog before signing up or booking a demo.
- Replies and reactions. Customer replies to the digest and reactions in shared Slack channels are the clearest signal that people care.
Common mistakes
- Auto-generating it from commits. incident.io deliberately keeps entries human-written, because reviewing changes by hand forces the question of why a customer should care.
- Listing everything equally. A dependency upgrade and a new feature should not get the same billing.
- Announcing what users cannot use. Only list changes that are generally available. Pilot features in a public log create support questions you cannot answer yet.
- Letting docs lag. If the changelog says a button moved and the help guide still shows the old screen, the announcement creates confusion. Update the guide in the same release.
- Going quiet. A missed month is visible to every visitor. Smaller, regular entries beat occasional big ones.
A minimal setup to start this week
- Create a public changelog page with dated, linkable entries and an RSS feed.
- Pick a day and an owner. Drafts from builders are due the day before; the owner edits and publishes.
- Write the first entry about the most useful change from the last two weeks, with one visual.
- Send it to customers by email and post the headline change on social.
- Tell sales and success which customers asked for what shipped.
After a quarter you will have a dozen entries that show steady progress, a set of reusable clips, and a habit. For related tactics, see our playbooks on documentation-led growth and free tools as a growth channel.