# Release Notes — v[VERSION]

> Fill in for human readers. Use Keep a Changelog change types. These notes are the customer-facing view of the same content tracked in CHANGELOG.md — keep them consistent. Delete the guidance notes once populated.

| Field | Value |
|-------|-------|
| Version | [e.g., 2.4.0] |
| Release date | [YYYY-MM-DD] |
| Release type | Major / Minor / Patch (per SemVer) |
| Status | Draft / In Review / Published |

## Summary

[2–3 sentences for a busy reader: what changed, why it matters, and whether any action is required.]

## Added

- [New capability — e.g., "Export to CSV is now available on the reports page."]

## Changed

- [Behavior change — e.g., "Default page size increased from 20 to 50."]

## Deprecated

- [Being phased out — e.g., "The v1 reports endpoint is deprecated and will be removed in v3.0."]

## Removed

- [Removed feature — e.g., "Legacy SMS notifications have been removed."]

## Fixed

- [Bug fix — e.g., "Fixed an issue where session tokens expired mid-checkout."]

## Security

- [Security fix — e.g., "Updated the auth library to address CVE-2026-XXXX."]

## Known Issues

- [Issue with a workaround — e.g., "On iOS < 17 the export button is hidden; upgrade the OS or use the web app."]
- [Issue being tracked for the next release — e.g., "The spinner does not render on very slow connections; tracked in #2345."]

## Breaking Changes and Migration

> Only fill this section if the version has breaking changes; otherwise state "No breaking changes in this release."

### Breaking changes

- [What is incompatible — e.g., "The `customer.list` endpoint now requires a `region` query parameter."]

### Migration steps

1. [Step 1 — e.g., "Update clients to send `region`."]
2. [Step 2 — e.g., "Run the provided migration script on any cached data."]

## Upgrade Instructions

1. [e.g., "Pull the new image: `docker pull registry.example.com/api:2.4.0`."]
2. [e.g., "Apply the schema migration: `migrate up` — expand-only, safe to run during the deploy."]
3. [e.g., "Deploy, then confirm the health endpoint returns 200."]
4. [e.g., "Monitor the error-rate dashboard for 48 hours."]

## Links

| Item | Link |
|------|------|
| Changelog | [link to CHANGELOG.md] |
| Diff (previous → this) | [link to compare v2.3.1...v2.4.0] |
| Artifact(s) | [registry / artifact URL] |
| Artifact digest(s) | [sha256:...] |
| SBOM | [link] |
| Migration scripts | [link] |
| Documentation | [link] |
| Security advisories | [link] |
| Support / feedback | [link] |

## Versioning

This release follows Semantic Versioning (MAJOR.MINOR.PATCH). Patch releases contain backward-compatible fixes; minor releases add backward-compatible features; major releases may contain breaking changes documented above.