Release Notes Checklist

Use semver: bump major for breaking changes, minor for backward-compatible features, patch for fixes. The release captain owns the version bump; double-check it matches the git tag (e.g., v2024.45.0) on the release branch.

Two to four sentences in customer-readable prose, not commit-message shorthand. Lead with the biggest user-visible change; do not mention internal refactors, dependency bumps, or test-only changes here. PM can edit later — get a draft down.

Pick three to five highlights for the top of the changelog. These should map to PRs that shipped behind feature flags now being flipped on, not every merged commit since the last tag.

Run git log --merges previous-tag..HEAD against the release branch and cross-reference Jira/Linear epics tagged for the milestone. Each feature gets a one-line user-facing description — not the PR title.

Performance wins, UX polish, expanded API surface on existing endpoints. Quantify when you can: "p95 dashboard load down from 1.8s to 600ms" beats "performance improvements."

Internal changelog links to GitHub PR + Jira/Linear ticket; public changelog links to docs or the public roadmap entry. Keep the two views consistent so support can trace a customer question back to the merging PR.

Pull from the support tag in Jira/Linear and the Sentry/Bugsnag issues marked resolved-in-release. Skip internal-only flakes and test-suite fixes — those are not customer-facing.

Public changelog uses the customer-visible reference ("resolved an issue affecting SAML login on the EU region"); internal changelog includes the ticket ID. Customers searching support tickets should find the matching changelog entry.

Disclose anything customers are likely to hit and the planned fix milestone. Hiding a known regression that surfaces in support within 24 hours of release damages credibility more than naming it up front.

Minimum Node/Python/Ruby version, supported browsers, mobile OS floors, container base-image bumps. If you dropped Node 16 support this release, that line goes here in bold — not buried in the upgrade section.

Removed endpoints, renamed fields, changed default values, stricter validation, response-shape changes. If yes, the migration guide step (later in this checklist) becomes required. For a major version bump this should be Yes; for minor or patch it should be No.

Each deprecation needs a removal target version or date — "deprecated, will be removed in v2025.10" is actionable; "deprecated" alone leaves customers guessing. Cross-link to the replacement API or feature.

Schema-only migrations are fast and reversible. Schema-plus-backfill migrations need a batched runbook so the backfill does not lock the table during peak traffic — adding a NOT NULL column with a default on a 50M-row Postgres table will take exclusive locks for hours.

For self-hosted customers: exact helm upgrade / terraform apply / docker-compose commands, in order, with expected output snippets. For SaaS-only releases, this section can simply state "No customer action required."

Confirm the previous container image is still in the registry (not pruned), the previous Helm release revision is rollbackable, and the migration is reversible. A rollback plan that has never been tested is not a rollback plan — note when this was last drilled.

Batch size, sleep interval between batches, replication-lag threshold to pause on, and how to resume from a partial backfill. Include the expected wall-clock duration on a representative customer dataset so SREs know whether to start it before or after the deploy window.

For each breaking change: before/after code snippet, the search pattern customers can grep their codebase for, and the deprecation timeline if there's a parallel-support window. Customers integrating against your API will paste these snippets directly into their PRs.

For open-source projects, list every external PR author by GitHub handle. For internal releases, name the feature owners and any cross-team reviewers (security, design, docs) who unblocked the work.

New packages added to package.json, requirements.txt, go.mod, Gemfile since the previous release. Confirm each license is on the approved list — GPL/AGPL copyleft propagation is the gotcha for proprietary distributions, and SBOM consumers will check.

Customer support email, dedicated Slack Connect channel for enterprise tier, status page URL. Note response-time expectations by tier so customers reading the changelog after-hours know what to expect.

Public GitHub Issues / Linear public board / Canny portal URL, plus a one-line note on what information to include in a report (version, browser, reproduction steps). Saves a round-trip for the on-call engineer triaging incoming reports.

PM reviews customer-facing wording and feature framing; engineering lead verifies technical accuracy of breaking changes and migration steps. Both must approve before the changelog is published — capture sign-off below.

Publish in lockstep with the deploy: changelog goes live as the canary reaches 100%. Update the Statuspage scheduled-maintenance window to closed, and post the URL of the live changelog entry below for traceability.

Three-sentence announcement linking the changelog, naming the release captain on-call for the next 24 hours, and flagging any breaking changes customers need to act on. Skip the email blast for patch releases; reserve it for major and minor.