Write useful release notes

Consumers read release notes to decide whether an upgrade is a five-minute npm bump or a migration project. A dump of commit hashes helps nobody.

Organize notes by user-visible impact, not by files touched. I keep a CHANGELOG.md in the repo and paste the relevant section into the GitHub release when I tag. npm also shows the README on the package page, so keep the top of that file current for people who never open GitHub.

Patch example (1.2.0 → 1.2.1)

## 1.2.1

### Fixed
- Titles with consecutive spaces no longer produce double hyphens.

### Upgrade
npm install @acme/slugify-title@^1.2.1
No code changes required.

Minor example (1.2.1 → 1.3.0)

## 1.3.0

### Added
- Optional `{ locale: 'de' }` on `slugifyTitle` for German umlaut handling.
  Default behavior is unchanged.

### Upgrade
npm install @acme/slugify-title@^1.3.0

Major example (1.3.0 → 2.0.0)

## 2.0.0

### Changed
- `slugifyTitle` now throws on empty strings instead of returning ''.
  Callers that relied on the old behavior must handle the error or pass a fallback.

### Migration
Before:
const slug = slugifyTitle(title)

After:
const slug = title ? slugifyTitle(title) : 'untitled'

Sections worth using

• Added for new exports or options
• Changed for behavior shifts
• Fixed for bug fixes
• Deprecated for features scheduled for removal
• Security when the release addresses a vulnerability

Ask a teammate to read the major notes cold. If they cannot predict the migration work in two minutes, add another concrete before/after snippet.

Git history stays in git. Release notes speak to the person running npm update on a Tuesday morning.

For security fixes, say which versions are affected and whether users must act immediately. “Fixed XSS” without a version range leaves people guessing.

Patch releases should read boring. That is a compliment. Excitement in patch notes usually means someone is downplaying a behavior change that should have been a major bump.

Link to the full changelog from the npm README when the project is active. Busy teams install from the registry page and never open GitHub unless you give them a reason.