writing-releases

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…

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