writing-releases

name	writing-releases
description	Writes GitHub release notes for Medusa releases in the established style. Use when generating a draft release description from a list of commits and PR metadata. Covers minimal patch releases, single-highlight releases, multi-feature releases, and releases with breaking changes.

Writing Medusa Release Notes

Generates GitHub release notes from commit/PR data in the established Medusa style.

Constraints

• Full Changelog link is mandatory — always the last line: **Full Changelog**: [vPREV...vNEW](compare-url)
• No top-level Breaking Changes section — breaking changes are embedded inside their Highlight subsection with 🚧 Breaking change, never in a separate ## Breaking Changes heading
• Bullet format is strict — every entry in Features/Bugs/Chores/etc. must include author link and PR link (see reference/format.md)
• Highlights are not a summary of all PRs — only significant changes qualify; routine additions go in Features/Bugs bullets only (see reference/release-types.md)
• No emojis — the only permitted emoji is 🚧 on breaking change highlights; use none anywhere else
• Code block required for actionable steps — if a highlight requires the developer to install a package, run a command, or update config, include a fenced code block with the exact command(s)

Load Reference Files When Needed

Load at least one reference file before writing.

Task	Load
Formatting sections and bullets	reference/format.md
Deciding whether to write Highlights, and identifying breaking changes	reference/release-types.md
Writing the Highlights section	reference/highlights.md

Quick Reference

Release type decision

Commit set	Release type
Only routine fixes/chores, no user-facing impact	Minimal — no Highlights section
One important change is the main reason for the release	Single Highlight
Multiple significant features or fixes	Multi-Highlight
Any PR with a minor changeset in .changeset/	Add 🚧 to that Highlight

Section order (include only sections with entries)

## Highlights
## Features
## Bugs
## Documentation
## Chores
## Other Changes
## New Contributors
**Full Changelog**: [vPREV...vNEW](url)

Common Mistakes

• Adding a title or # Heading at the top — release notes have no title, start directly with the first section
• Adding a ## Breaking Changes top-level section — embed inside the Highlight instead
• Putting a routine bug fix or small feature addition in Highlights
• Missing the Full Changelog link at the end
• Bullet missing author link or PR link
• Using PR title verbatim as a Highlight heading — write a descriptive outcome-focused title
• Treating every feat: commit as a Highlight candidate
• Using emojis anywhere except 🚧 on breaking change highlights
• Writing a Highlight that requires a developer action (install, run, config change) without a fenced code block

Reference Files

reference/format.md          — section order, bullet format, commit prefix → section mapping
reference/release-types.md   — when to add Highlights, breaking change detection, highlight criteria
reference/highlights.md      — how to write Highlight subsections