<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Examples — Release Notes House Style

## Contents
- Bullet-level pairs (do / never)
- Breaking-change placement
- Complete before/after release

## Bullet-level pairs (do / never)

**Pair 1 — benefit first**
- ✅ "Dashboards now refresh automatically every 30 seconds — no more manual reloads."
- ❌ "Implemented WebSocket-based polling refactor for dashboard state (JIRA-4521)."

**Pair 2 — plain language**
- ✅ "Fixed a bug where exported CSVs dropped the last row."
- ❌ "Resolved an edge-case regression in the serialization pipeline impacting terminal record emission."

**Pair 3 — noise cut**
- ✅ (entry omitted entirely)
- ❌ "Bumped lodash from 4.17.20 to 4.17.21."

**Pair 4 — no filler**
- ✅ "Fixed three crashes on startup affecting Windows users with non-Latin usernames."
- ❌ "Various bug fixes and performance improvements."

## Breaking-change placement

✅ Correct — top of the notes, before any heading:

```markdown
## Acme CLI 3.0.0 — 2026-08-01

> **Breaking:** `acme deploy` now requires `--env`. Add `--env production` to existing scripts.

This release focuses on safer deployments.

### Added
- ...
```

❌ Wrong — buried as a bullet:

```markdown
### Improved
- Deploy command now requires an environment flag (breaking).
```

## Complete before/after release

**Input (engineer's commit list):**

```
- feat: add SSO via SAML (ENG-201)
- perf: rewrite query planner, p95 latency 840ms -> 210ms
- fix: null pointer when profile avatar missing
- chore: upgrade CI runners to ubuntu-24.04
- refactor: extract billing module
- feat!: remove legacy /v1/auth endpoint
```

**❌ Never ship this (implementation-first, noise included, breaking buried):**

```markdown
## 2.8.0
- Added SAML SSO support (ENG-201)
- Rewrote query planner
- Fixed NPE on missing avatar
- Upgraded CI to ubuntu-24.04
- Extracted billing module
- Removed /v1/auth (breaking)
```

**✅ House style:**

```markdown
## Acme 2.8.0 — 2026-08-05

> **Breaking:** The legacy `/v1/auth` endpoint is removed. Switch integrations to `/v2/auth` before upgrading.

Faster searches and single sign-on headline this release.

### Added
- Sign in with your company account: SAML single sign-on is now available on all Team plans.

### Improved
- Search is dramatically faster — most queries now return in about 0.2 seconds instead of nearly a second.

### Fixed
- Fixed a crash when opening a profile that has no avatar.
```

Note: the CI upgrade and billing refactor are correctly absent (no user impact).