How to write release notes for SaaS
Explain availability and customer actions, not just what merged.
01Separate shipping from availability
A merged feature may still be behind a flag. Name the eligible plans, roles and regions, the rollout start, and whether an administrator must enable it. Do not tell all customers a feature is live when only a pilot cohort can use it.
02Write for the person doing the work
Lead with the task that changed, then give the navigation path and prerequisites. A billing administrator needs an export location and permission requirements, not the internal name of your reporting service.
03Describe behavior changes before benefits
If a default changed, state the old and new behavior. Include whether existing workspaces keep their setting. Give administrators a way to test the new behavior before a company-wide rollout.
04Keep an engineering trail alongside the announcement
A UI-only announcement does not need an invented package version. When you ship an SDK or API alongside it, publish its actual version and structured migration details so agents can distinguish a client upgrade from a hosted UI change.
Before and after
Too vague
Improved reporting for everyone.
Specific and actionable
CSV exports are available to workspace admins on Business. Open Reports → Export. Existing scheduled exports are unchanged. The API client change is documented separately in SDK 2.0.0.
Fictional example — use your own verified names, versions and behavior.
Before you publish
- Confirm plan and role eligibility
- Test the documented UI path as a customer
- Name rollout exceptions
- Link API or SDK changes to a version
Common questions
Keep reading
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.