Release Notes Writing Exercises

1 / 5

A developer is writing release notes for an authentication change. Which entry is most effective for a developer audience consuming an API change?

Effective release notes for a developer audience are specific, factual, and include: what changed exactly, who is affected, whether it is breaking or not, and a reference (issue/PR number).

Principle	Example
Specific over vague	Name the exact field, endpoint, or behaviour that changed
User impact framing	State the before behaviour and the after behaviour
Issue reference	Link to the bug/ticket for context and traceability
Breaking label	Flag as breaking or non-breaking so consumers can prioritise upgrade

2 / 5

A product manager writes this release note introduction: "In this release we added lots of great new features that will improve your workflow and make your daily tasks easier!"

What is wrong with this introduction for a technical audience?

Release note audience determines tone. End-users may accept benefit-focused language. Developers and engineers need: what exactly changed, configuration impact, migration steps. Marketing language ("great new features!") is noise to a technical reader.

Audience	Appropriate tone	Example
End users	Benefit-focused, plain language	"You can now export reports as CSV."
Developers / engineers	Precise, factual, technical	"Added: `GET /reports/export?format=csv` endpoint."

Key vocabulary: tone register, audience-appropriate language, feature description vs. benefit description.

3 / 5

A release includes a breaking change to a widely-used API endpoint.

Where in the release notes should breaking changes be positioned?

Breaking changes need maximum visibility: prominent placement at the top, an explicit warning marker, a description of what broke, a migration path, and a deprecation timeline. Burying breaking changes creates support burden and damages user trust.

Required element	Example
Warning marker	⚠️ Breaking Change / BREAKING
What broke	Specific field, endpoint, or contract that changed
Migration path	Step-by-step instructions for upgrading
Timeline	When the old behaviour is fully removed

Key vocabulary: breaking change notice, migration guide, API contract violation, consumer communication.

4 / 5

A team is writing release notes and wants to follow the "Keep a Changelog" convention.

Which headline format best follows Keep a Changelog conventions?

Keep a Changelog format: ## [version] — YYYY-MM-DD. Version in brackets, ISO date, optional annotation. Consistent format enables automated tooling (diff generation, changelog parsing, release notes aggregation).

Section	Purpose
Added	New features
Changed	Changes to existing functionality
Deprecated	Features soon to be removed
Removed	Features removed in this release
Fixed	Bug fixes
Security	Security vulnerability fixes

Key vocabulary: Keep a Changelog, SemVer versioning labels, date-stamped entries, Unreleased section.

5 / 5

A library releases a new major version (v3.0.0) with significant breaking changes. The release includes upgrade instructions.

What should upgrade instructions minimally include for a breaking major version release?

A migration guide for a breaking major version should include: what to change (specific config or code), before/after comparison, deprecated API replacements, and timeline (deprecated → fully removed). The goal is to make upgrading deterministic.

Component	Example
Migration commands	`npx migrate-v3` or specific config changes with code samples
Before/after comparison	Side-by-side diff showing old API vs. new API usage
Deprecated API replacements	Old method → new alternative mapping table
Support timeline	v2.x supported until YYYY-MM-DD; migrate before that date

Key vocabulary: upgrade path, backward compatibility window, version support policy, deprecation notice.