By name: release-notes description: "Draft GitHub release bodies for Composer packages. Covers structure, voice, breaking-change callouts, and what to omit." metadata: boost-tags: "release-automation"
Release notes
When to apply
- Asked to draft a GitHub release body
- Reviewing a PR that bumps the version
- Asked to "summarize what's new" for a tag
Structure
Top-level sections at ## ; no umbrella heading. Omit any section with no entries.
## Breaking
- (only if MAJOR or pre-1.0 minor with breaking change — be explicit)
## Added
- (new features, new public API surface)
## Changed
- (behavior changes, content updates that aren't bug fixes)
## Fixed
- (bug fixes, security fixes)
## Internal
- (refactors, dev-only changes, dep bumps — keep terse)
**Full changelog:** v1.2.3...v1.3.0
No leading version heading (# 1.2.3). The GitHub release page already shows the version as its title; repeating it in the body is duplicate.
No marketing-tone, audit-narration, or framework-fold-in intro paragraphs. Don't lead with "This release ships X, Y, Z..." (summarizes; the section list already covers it), "Polish-tier patch bundling..." (internal classification), "Validates the asymmetric-cadence frame..." (internal pattern-tracking), or audit-narration of how the work was produced.
A short opening paragraph (or a ## Why this matters / ## Background section) IS OK when the release closes a non-obvious bug class, changes user-visible behavior in a way the section-list can't fully explain, or names the upgrade-decision context (e.g. "Operators on Laravel projects who wired X experienced silent Y"). The test: does the paragraph give a reader information they need to decide whether/how to upgrade, beyond what the section list already conveys? If yes, keep it terse and informational. If no, drop it.
Bullets by default, paragraphs only when justified. A bullet should be one line. If a change needs context that doesn't fit, the bullet can include a second sentence; a full paragraph is justified only when a behavior or migration genuinely needs prose explanation. Long prose embedded in bullets reads as audit-narration, not release notes.
Voice
- Past tense ("added X", "fixed Y")
- One entry per change, one line each. If it needs two lines, the second one carries operational consequence (migration step, version requirement, deprecation timeline), not narrative context.
- Link PR numbers:
Added foo (#42) - Credit external contributors:
Added foo (#42) — thanks @contributor
Breaking changes
Always callout breaking changes explicitly with migration code:
## Breaking
- Renamed `Foo::oldMethod()` to `Foo::newMethod()`. Migrate:
```php
// before
$foo->oldMethod($arg);
// after
$foo->newMethod($arg);
## Adoption / upgrade block (optional)
If the release has a notable adoption shape (constraint bump + migration command, new vendor floor, etc.), close with a short fenced block — NOT a section heading + prose. Three-line code block beats a 20-line paragraph.
composer require --dev "vendor/package:^1.2" vendor/bin/whatever migrate
If adoption is the same as the prior version (just `composer update`), omit the block entirely.
## Anti-patterns
Conceptual quality issues — see "What to omit" below for the specific structural things to leave out.
- "Various improvements" — useless. Be specific.
- Marketing tone ("massive new feature!") — let users decide what's massive.
- Burying breaking changes in "Internal".
- Duplicating commit messages verbatim — synthesize, don't transcribe.
## What to omit
**Omit needless words** — aggressively. Release notes are for developers checking what changed; everything else is bloat.
**Always omit:**
- **Leading `# <version>` heading** — release title covers it.
- **Marketing-tone / audit-narration / framework-fold-in opening paragraphs** before the first `## ` section. A short value-add intro explaining a non-obvious bug class or upgrade-decision context is fine — see "No marketing-tone..." in Structure above.
- **`## Requires` / `## Dependencies` saying "unchanged from prior".** If nothing changed, don't write the section.
- **`## Validation` / quality-gate counts** ("27/27 skills + 1/1 guideline manifest valid", "PHPStan baseline drift: none"). CI green is implied; consumers don't read release notes for QA evidence.
- **`## Acknowledgments` / pattern-tracking sections** ("Ships absorption-pattern data point #2", "Validates the asymmetric-cadence frame"). Internal observation — belongs in strategy docs or internal notes.
- **`## Internal` quality-gate detail** ("No PHPStan baseline drift, no schema changes"). Same — implied by passing CI.
- **Dogfooding narrative** ("Bug surfaced during proving consumer's adoption cycle when..."). Bullet the FIX; don't narrate the discovery.
- **Process choreography** (named release cadences, "Per the load-bearing-only floor-pin rule we codified..."). Internal framework, not developer-facing.
- **Peer-handle credits / internal session IDs.** Real-name or @-handle credits OK; internal peer codes (`b020i4st` etc.) never.
- **Dependency bumps to other packages** unless they affect users — then callout the implication, not the bump.
- **Internal test refactors, README typo fixes.**
- **"Unchanged from prior" segments** in any section. If it's unchanged, don't list it.
## Verified-sha line
Pre-release tooling (`pre-release` skill, step 7) requires the first line of the notes file to be an HTML comment recording the green CI SHA:
```markdown
<!-- verified-sha: 4387b6845b45def9c6ad80e638990f81b74bfb19 -->
## Changed
...
HTML comments are stripped by GitHub on render — the line is invisible in the published release body. It's an internal verification anchor for the pre-tag gate, not user-facing content. Keep it as the first line; do not promote it to a visible section.
The SHA must be a real, green commit — never a placeholder. Do not write <!-- verified-sha: TODO -->, REPIN-TO-GREEN-SHA, or a SHA recycled from the previous version's notes. A placeholder is not a "draft in progress" — it is a notes file that defeats the pre-tag gate (which matches this line against live HEAD). If you don't yet have the green SHA from pre-release step 6, you are not ready to write this file at all.
Do not write or edit this file before pre-release step 6 is green on the actual release commit. This skill owns the notes' content; pre-release owns when the file may exist. The two rules that have bitten us: (1) a notes file carried over from the last version is deleted and redrafted, never edited in place pre-green — "fixing the content" of a stale file still produces a premature, placeholder-pinned draft; (2) in a PR-based release the green commit is the post-merge commit on the release branch, not the feature-branch tip, so the SHA you pin comes from re-running step 6 after the PR merges.
Example — good shape
Section order follows the Structure list (Breaking → Added → Changed → Fixed → Internal). Sections without entries are omitted.
<!-- verified-sha: 4387b6845b45def9c6ad80e638990f81b74bfb19 -->
## Added
- `CONTRIBUTING.md` patterns section codifying the wording-revert-as-regression-test pattern and the meta-rule for when to codify patterns (wait for 2-3 occurrences across distinct contexts).
## Changed
- Diagnostics header renamed to `Diagnostics` (from the legacy conventions-only label). Now covers conventions, stale-removal info, Copilot strip info, and render-fail warnings.
## Fixed
- `SyncCommand` now renders diagnostics before the error short-circuit. Previously, top-level errors hid the safety-gate reassurance alongside them.
**Full Changelog**: https://github.com/SanderMuller/boost-core/compare/0.9.3...0.9.4
Versus the verbose shape that triggered this guidance — same release, ~3× the length, opens with a 4-line audit paragraph, embeds dogfooding narrative inside ## Fixed, ships an ## Internal section consisting of "no drift, no changes, no surface changes" tautologies. Same information density, ~30% as readable.