| name | release-notes |
| description | Use when drafting GitHub release bodies from a tag range or staged changes. Default: GitHub's auto-generated format; override only on major/breaking. Laravel notes in `references/laravel-package.md`. Activates: writing release notes, drafting a release announcement, summarizing a tag range; mentions: release notes, GitHub release, RELEASE_NOTES. |
Release Notes
Generic guidance for writing GitHub release bodies. Ecosystem-specific conventions live in references/.
Reference pointer
Working on a Laravel package? Also apply references/laravel-package.md from this skill directory — it covers version-matrix shifts, ecosystem-plugin constraint changes, and how a CHANGELOG-automation workflow consumes the release body.
Heuristic: it's a Laravel package if composer.json's require lists laravel/framework, any illuminate/*, or any filament/* / livewire/* / laravel/nova ecosystem package. Pure-PHP libraries skip the reference.
Default: trust GitHub's auto-generator
The 2026 reality across well-maintained Laravel/Spatie packages: release bodies are minimal. Surveyed sample of 5 recent releases (Spatie laravel-permission 7.4.1, laravel-data 4.22.1, laravel/horizon v5.46.0, awcodes/filament-curator v5.0.7, barryvdh/laravel-debugbar v4.2.8) all use either:
- A single
## What's Changed H2 with PR-linked bullets (title by @author in <PR url>) plus a trailing **Full Changelog**: <compare-url> line.
- Or no headings at all (Horizon).
This matches GitHub's "Generate release notes" button output exactly. Use it as the default. For patch and most minor releases, no further prose is required.
## What's Changed
* Fix typo in middleware by @alice in https://github.com/vendor/repo/pull/123
**Full Changelog**: https://github.com/vendor/repo/compare/v1.2.0...v1.2.1
When to override the default
Override only when one or more of these is true:
- Major version bump (X.0.0).
- Breaking changes in any dimension (API, minimum PHP, minimum Laravel, removed features).
- Multi-PR feature that needs a narrative — readers won't piece it together from PR titles.
- Ecosystem dep change (Filament/Livewire/Nova major bump).
Don't override for routine work. Auto-format suffices and matches reader expectations.
Override structure
When overriding, layer minimal added structure on top of the auto-bullets:
<one-line summary describing the headline change in user terms>
## Highlights
- <user-facing bullet, ≤ 5 items>
## Breaking changes
- <what breaks>. See [UPGRADING.md#anchor](UPGRADING.md#anchor) for migration steps.
- <next break>. See [UPGRADING.md#another-anchor](UPGRADING.md#another-anchor) for migration steps.
## What's Changed
<auto-generated PR bullets here>
**Full Changelog**: <compare-url>
Sections are conditional. Drop "Highlights" if there's nothing user-facing to highlight. Drop "Breaking changes" if there are none — adding an empty section just to have one is worse than omitting.
## Breaking changes bullet contract. Every bullet must end with a link to the matching UPGRADING.md anchor. Operational migration steps (before/after code, multi-line procedures) live in UPGRADING.md, not the release body — see the upgrading skill for how to write that file. Verify before publishing that every bullet's link resolves to an existing anchor; broken links break readers' upgrade flow.
Bookwork to cut
Common sections that bloat release bodies without serving readers. Cut all of these unless you have a strong reason:
- "Internals" / "Implementation details" — belongs in the PR description, not the release body. Release readers want behavior changes, not how.
- "Why now" / context-setting paragraphs — readers know why they're reading; lead with what changed.
- "Compatibility" when nothing breaks — silence already says this. Six lines saying "no breaking changes" is worse than zero lines.
- "Test hygiene" / "Verified" sections —
vendor/bin/pest passing isn't release-worthy news.
- Multi-paragraph rationale before the change list — one summary line, then bullets. Save the essay for a blog post.
### Recovering a corrupted X-style remediation prose for niche edge cases — link a docs page or pinned issue; don't inline it in the release body for the 99% who won't hit the bug.
If your draft has any of these, delete first, ask "is the release weaker without it?" If yes, restore. Usually no.
Tag-range workflow
Generating notes from scratch:
- Identify the previous tag:
git describe --tags --abbrev=0 (returns the most recent reachable tag from HEAD).
- Get the commit list:
git log <prev-tag>..HEAD --oneline.
- Skim for breaking-change footers in commit bodies (
git log <prev-tag>..HEAD --grep='BREAKING').
- Group commits by theme (not necessarily by conventional-commit type — survey shows that's rare in Laravel).
- Write the one-line summary first; everything else falls out of it.
- Use GitHub's "Generate release notes" button for the auto-bullet section if available; it's faster and more accurate than hand-listing PRs.
CHANGELOG workflow
If the repo already maintains a hand-written CHANGELOG.md entry for the version, the release body should mirror or summarize that entry, not re-derive it from git. Hand-written CHANGELOG > auto-generated bullets when both exist.
If the repo uses a CHANGELOG-automation workflow (e.g. stefanzweifel/changelog-updater-action), the GitHub release body becomes the CHANGELOG entry verbatim — write the body assuming readers will see it both on the releases page and in CHANGELOG.md. Don't write "as discussed in the issue tracker" prose; CHANGELOG readers don't have that context.
Voice
- Lead with impact, not refactor terminology. "Allow custom drivers" not "Refactor driver resolution to allow custom implementations."
- User-facing language. Internal cleanups can stay terse ("Internal: removed deprecated
OldThing").
- Link PR # and
@author for technical readers.
- Past tense for what shipped ("Added", "Fixed"), not future tense.
- No "we" / "our" — prefer the active package voice.
Cross-refs
readme skill — when a release ships sections that need README updates, pair the work.lean-dist skill — when a release changes which files ship in the dist tarball.package-development skill — Laravel package release context.
