release-notes

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:

1. Identify the previous tag: git describe --tags --abbrev=0 (returns the most recent reachable tag from HEAD).
2. Get the commit list: git log <prev-tag>..HEAD --oneline.
3. Skim for breaking-change footers in commit bodies (git log <prev-tag>..HEAD --grep='BREAKING').
4. Group commits by theme (not necessarily by conventional-commit type — survey shows that's rare in Laravel).
5. Write the one-line summary first; everything else falls out of it.
6. 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.