Writing Release Notes for a Major Version (v2.0.0)
How to write comprehensive release notes for a major version bump. Covers structuring breaking changes, new features, migration guides, and contributor credits.
Major Releases
Detailed Explanation
Major Release Notes Structure
A major version release (e.g., v2.0.0 under Semantic Versioning) signals breaking changes that require users to update their code. The release notes for a major version need to be especially thorough because users rely on them to plan their upgrade.
Essential Sections
- Version Header with the date and optional codename
- Highlights Summary covering the most impactful changes in 2-3 sentences
- Breaking Changes listed prominently at the top, each with migration steps
- Added section for all new features
- Changed section for modified behaviors
- Removed section for deleted features
- Contributors thanking the team
Example Structure
## [2.0.0] - 2026-02-28 (Aurora)
This release introduces a completely redesigned API, native TypeScript
support, and tree-shaking compatibility.
### BREAKING CHANGES
> The `init()` function now requires a configuration object instead of
> positional arguments. See the migration guide for details.
### Added
- Native TypeScript type definitions
- Tree-shaking support for ESM builds
- New `createClient()` factory function
### Changed
- Minimum Node.js version is now 18
- Default timeout increased from 5s to 30s
### Removed
- Legacy callback-based API (use async/await instead)
- Support for Node.js 14 and 16
### Contributors
- @alice - API redesign
- @bob - TypeScript types
Best Practices
- Always link to a migration guide when there are breaking changes
- Group breaking changes by impact area (API, config, behavior)
- Include before/after code snippets for changed APIs
- Mention the minimum upgrade path (e.g., "upgrade from v1.9 first")
Use Case
Releasing a major version of an open-source library, framework, or CLI tool where users need clear guidance on what changed, what broke, and how to migrate their existing code.