Two audiences, two sections. An internal changelog that's terse, complete, and engineer-facing, and customer-facing notes that are plain language and benefit-focused, no jargon.
Don't make one document serve both badly. Split them as shown below.
How to use this document
- Write the internal changelog as you go (per-PR or per-merge); write the customer-facing summary right before publishing.
- If a change has no user-visible effect, it doesn't belong in customer-facing notes even if it's a big engineering lift ("rewrote the queue internals" is not customer news unless it changed behavior they can see).
- Always link the version/date so support and engineering can cross-reference a ticket to a release.
Release [version/date]
Release date: [YYYY-MM-DD]
Deployed by: [name/team]
Rollout: [all at once / staged % / behind flag [flag_name]]
Customer-facing summary
Plain language. Lead with the benefit, not the mechanism.
One line per item unless it needs a screenshot or GIF.
New
- [Feature name], [what the user can now do, in their words, e.g. "Export any table to CSV directly from the table view."]
Improved
- [What got better, e.g. "Search results now load in under 200ms for workspaces with 10k+ documents."]
Fixed
- [User-visible bug fixed, described from the user's perspective, e.g. "Fixed an issue where uploaded images sometimes failed to display on mobile."]
Deprecated / removed
- [Anything the user needs to know is going away, with a timeline, e.g. "The legacy export format will be removed on [date]; please migrate to CSV."]
Internal changelog
Complete, terse, technical. Every merged PR that touched behavior gets a line.
This is your source of truth when someone asks whether X shipped, six months from now.
| Type | Description | PR/ticket | Author |
|---|---|---|---|
| Feature | [description] | [#123] | [name] |
| Fix | [description] | [#124] | [name] |
| Perf | [description] | [#125] | [name] |
| Chore | [description, e.g. dependency bump] | [#126] | [name] |
| Breaking | [description, flag clearly, link migration notes] | [#127] | [name] |
Migration / action required
If a change requires the customer or another team to do something, say so explicitly. Don't bury it in the list above.
- [e.g. API consumers must update to
v2endpoint before [date];v1will return 410 after that.] - [e.g. No action required]
Rollback plan
Only needed for risky releases, but it's good hygiene to have a default answer anyway.
[e.g. "Revert via one-click rollback in deploy tool. No DB migration was applied, so rollback is safe at any point in the next 24h." Or: "Migration is one-way. Rollback requires restoring from the pre-deploy snapshot, see runbook link."]
Example: filled entry
Release 2.14.0 (2026-03-04)Customer-facing summary
New: Export any table to CSV directly from the table view. Look for the export icon in the top-right toolbar.
Improved: Search now returns results in under 200ms, even for workspaces with 10,000+ documents (previously up to 2s for large workspaces).
Fixed: Fixed an issue where uploaded images occasionally failed to render on mobile Safari.
Internal changelogTypeDescriptionPRFeatureCSV export endpoint + UI button on table view#412PerfAdded search index for workspace-scoped queries, cut p95 search latency 8x#409FixCorrected MIME type handling for HEIC uploads on iOS Safari#415
이 템플릿을 팀 워크스페이스로 복제하려면 → rootr.io