A time-ordered, human-facing record of what shipped in each release — new features, deprecations, fixes, and migration guidance. Release notes are the consumer-facing companion to a change log; where a change log catalogs every commit-level change, release notes summarize the things consumers need to act on or celebrate. They are essential for any API with paying customers and for any team that wants to set explicit expectations about pace and stability.

Also known as: Release Log, Releases, What's New, Updates, Product Updates

Example

- type: ReleaseNotes
  url: https://developers.example.com/releases

Standards

• Community Semantic Versioning 2.0
• Community Keep a Changelog 1.1
• IETF Atom Syndication Format (RFC 4287)
• Schema.org schema.org Article

OpenAPI Expression

• info.version (OpenAPI 3.x) — Anchors each release-notes entry to a specific version of the spec.

Link Relations

• alternate — HTML Living Standard
• prev / next — IANA Link Relations

Risk & Compliance

Compliance:

• Customer notification requirements may apply to deprecations and breaking changes — keep dated, archived release notes for audit.

Security: Release notes for security fixes need coordinated-disclosure discipline — describing a vulnerability before patches are deployed can hand attackers a roadmap. Maintain a separate security-advisory channel for CVE-class fixes and link to it rather than describing exploitable details inline.

Tools

• GitHub Releases — Releases tied to git tags
• release-please — Automated release-notes generator (Apache-2.0)
• Conventional Changelog — Generates notes from conventional-commits history (ISC)
• Bump.sh — Spec-diff release notes for API providers

Suggested Metrics

• release_cadence — Median time between published release-notes entries.
• breaking_change_count — Number of breaking-change entries per quarter — a stability indicator.
• notes_to_deprecation_lead_time — Days between a deprecation being announced in release notes and the affected feature being removed.

Example Implementations

• Stripe — Versioned API changes published per release with migration guidance.
• GitHub — Public changelog for the GitHub platform, including REST and GraphQL APIs.
• Twilio — Per-product release notes across the Twilio suite.

Related Properties

• Change log
• Versioning
• Deprecation policy
• Road map

Tags

• Lifecycle
• Versioning
• Communication

All Common Properties