Skip to content
Product Lifecycle Templates

Release Notes

beta  ·  Family delivery-docs  ·  Phase deliver  ·  Sizes lean, full  ·  ~1,550 tokens

Communicates what changed in a release to users and stakeholders, so people know what is new, what to do, and what to watch for.

Fast reference for the Release Notes bundle. For the full reasoning, history, and sources, read release-notes_companion.md.

When to use

Section titled “When to use”
  • To tell users and stakeholders what changed in a release and what to do about it.
  • At every release; even a small one gets an entry.
  • When a release includes anything users must act on (new capability, breaking change, known issue).

When NOT to use

Section titled “When NOT to use”
  • You need the permanent, complete, structured record of every change. Keep a changelog (Keep a Changelog format); derive the notes from it.
  • You need the project’s register of requested changes to an agreed baseline, each with its decision and who made it. That is a governance document that shares the word, not a software changelog: use change-log.
  • You need a full launch plan and comms. Use a launch checklist and announcement; release notes are one input.

Pick a variant

Section titled “Pick a variant”
  • Lean (default): the customer-facing announcement (Summary, New, Improved, Fixed) in plain, benefit-led language. For routine releases.
  • Full: adds Highlights, Changed, Deprecated, Removed, Security, Breaking changes and upgrade notes, and Known issues. For major or breaking releases, or notes that double as the changelog entry. Grow lean into full by adding sections; never reorder the shared ones.

First release (0.1.0)? Delete the comparative sections, do not fill them.

Section titled “First release (0.1.0)? Delete the comparative sections, do not fill them.”

Improved, Fixed, Changed, Deprecated, Removed, and Breaking changes are all defined against a previous release. A first release has none, so everything you shipped is New. Delete them rather than writing “None in this release” under each: a first release note declaring that nothing was improved and nothing was fixed is false about the work and a poor first impression. This is the single case that overrides the normal “write None rather than delete” rule. Keep a Changelog treats a first release as entirely “Added”, for the same reason.

The exception worth knowing: if real users have been living on an untagged main, things did change for them since they last pulled, so the comparative sections can carry that. If you do this, say so in the Summary, so the reader knows what “improved” is being measured against.

(This rule exists because the library’s own v0.1.0 release note hit the gap on the first real use of this template. See DF-1 in release-notes_history.md.)

Quality rubric (self-grade before publishing)

Section titled “Quality rubric (self-grade before publishing)”
  • Each entry leads with user benefit, in plain language, not implementation detail.
  • Changes are grouped so a reader can scan to what matters.
  • The summary says something specific, not “various improvements and bug fixes.”
  • Breaking changes are surfaced with a concrete upgrade path.
  • Security-relevant fixes are called out separately, with severity.
  • Known issues are listed honestly, with workarounds where they exist.
  • The date is ISO 8601 (YYYY-MM-DD); the version follows a stated scheme (e.g. SemVer).
  • All guidance comments deleted; no placeholders remain.

Named anti-patterns (the usual wrecks)

Section titled “Named anti-patterns (the usual wrecks)”
  1. Git-log dump. Pasting raw commit messages as notes.
  2. Written for the shipper. Implementation language instead of user benefit.
  3. “Various improvements and bug fixes.” A summary that communicates nothing.
  4. Hidden breaking changes. A breaking change with no flag and no upgrade path.
  5. Security buried in “Fixed.” A security fix with no separate visibility or severity.
  6. No known issues. Omitting known problems so users hit them unprepared.

The artifacts

Section titled “The artifacts”

release-notes_template-lean.md · ~1,550 tokens

---
title: "{{product}} {{version}}"
doc_type: release-notes
size: lean
owner: "{{owner}}"
status: draft
doc_version: "{{version}}"
created: "{{date}}"
updated: "{{date}}"
related_links: []
source_template: release-notes
source_template_version: 0.1.1
---


<!--
LEAN RELEASE NOTES. The customer-facing announcement: what is new, what got better, what was fixed,
in plain language framed around user benefit. Use this for a routine release. To grow it into full
notes, ADD sections (see release-notes_template-full.md); never rename or reorder the ones below (the
full variant is a strict superset of this one). Write for the user who needs to make sense of the
change, not the team that shipped it.


HOW TO FILL THIS IN
1. Read the comment under each heading: WHAT it wants, WHY it matters (with a pointer into
   release-notes_companion.md for the deep reasoning), guiding questions to ASK, a GOOD and a WEAK
   example, and the TRAP to avoid.
2. Replace each {{placeholder}} with your content.
3. If a section does not apply, write "None in this release" rather than deleting it.
4. FIRST RELEASE? Delete "Improved" and "Fixed" instead. They are defined against a previous release,
   and a 0.1.0 has none: everything you shipped is New. Writing "None in this release" under them is
   worse than deleting them, because it reads as "we improved nothing and fixed nothing," which is
   false about the work and a bad first impression. This is the one case where rule 3 does not apply.
   (Keep a Changelog treats a first release as entirely "Added"; same logic.) If your project has had
   real users on an untagged main for a while, you may keep both sections and describe what changed
   FOR THEM since they last pulled: say so in the Summary, so the reader knows what "improved" is
   measured against.
5. Before you ship: self-grade against release-notes_guide.md, then DELETE every HTML comment. They
   are guidance, not content.
-->


# {{product}} {{version}}


<!-- WHAT  The product name, version, and release date, plus whether the project follows a stated
           versioning scheme (SemVer).
     WHY   Readers orient on what shipped and when before reading any change. Deep dive:
           release-notes_companion.md section 3 (Anatomy > Release header).
     ASK   What product and version is this? What date did it ship? Do you follow SemVer?
     GOOD  "Release date: 2026-06-30. Acme Analytics follows Semantic Versioning."
     WEAK  "Released this week." (no ISO date, no version scheme; ambiguous across regions)
     TRAP  Non-ISO dates that read differently across regions; use YYYY-MM-DD per Keep a Changelog. -->


## Summary


<!-- WHAT  One or two sentences on what this release is about, in user terms: the headline change and
           who benefits.
     WHY   The summary is the triage surface; a reader decides from it whether to read on. Deep dive:
           release-notes_companion.md section 3 (Anatomy > Summary).
     ASK   What is this release about? What single change matters most? Would a user recognize the
           benefit from this line alone?
     GOOD  "This release introduces Saved Views, so you can capture a dashboard's filters once and
           reopen them in a click, and improves dashboard load time."
     WEAK  "Various bug fixes and improvements." (a summary that tells the reader nothing)
     TRAP  "Various improvements and bug fixes" - a summary that communicates nothing specific. -->


{{summary}}


## New


<!-- WHAT  New capabilities (Keep a Changelog "Added"), each a benefit-led headline with a short
           description. Lead with what the user can now do, not how it was built.
     WHY   Readers check "what's new" first; this is the section that earns adoption. Deep dive:
           release-notes_companion.md section 3 (Anatomy > New).
     ASK   What can the user now do that they could not before? What is the benefit in their words?
           Have you led with the outcome, not the implementation?
     GOOD  "**Saved Views**: Save a dashboard's filters, date range, and visible columns as a named
           view, reopen it in one click, set one as your default, and share it with your team."
     WEAK  "Implemented enhanced data persistence layer for improved throughput." (implementation
           language; the user cannot tell what changed for them)
     TRAP  Written for the shipper: implementation detail instead of user benefit. -->


- **{{feature_headline}}**: {{benefit_description}}


## Improved


<!-- WHAT  Enhancements to existing functionality (Keep a Changelog "Changed", the user-positive
           subset): speed, workflow, UI. Frame as the impact the user feels.
     WHY   It shows responsiveness to user needs; state the impact, not the internal change that
           produced it. Deep dive: release-notes_companion.md section 3 (Anatomy > Improved).
     ASK   What got better for the user? Can you state it as impact ("twice as fast")? Would the user
           recognize the thing you named?
     GOOD  "Dashboards now load noticeably faster on large datasets (illustrative: about 30 percent
           faster at p95)."
     WEAK  "Optimized the query execution planner." (an internal component name the user has never
           heard, with no stated impact)
     TRAP  Naming the internal change instead of the impact the user feels. -->


- {{improvement_1}}


## Fixed


<!-- WHAT  Resolved issues in plain language: what the user experienced before versus what happens
           now. Frame positively (what now works), but honestly.
     WHY   Users want to know their specific pain is gone, in terms they recognize. Deep dive:
           release-notes_companion.md section 3 (Anatomy > Fixed).
     ASK   What did the user experience before? What happens now? Is it stated in user terms, not bug
           IDs?
     GOOD  "Fixed an issue where the date-range picker occasionally reset to 'last 7 days' after
           switching tabs."
     WEAK  "Fixed BUG-4821, BUG-4822, BUG-4830." (raw bug IDs with no user-facing meaning)
     TRAP  Dumping raw bug IDs or commit messages with no user-facing meaning (the git-log dump). -->


- {{fix_1}}

Provenance

Section titled “Provenance”

The reasoning, the history and every source, in the repository:

  • Companion - the long-form argument: why these sections, where the sources disagree, and what the bundle refuses to claim
  • History - what changed in this bundle, and when
  • Research log - every source consulted, with what each one actually supports
  • Catalog metadata - the machine-readable record this page is generated from

Catalog record: 12 sections across 1 format(s), methodology methodology-agnostic, typically owned by PM / Release Manager.