Write Release Notes

A release note is a contract diff: what changed for the reader and what they must do about it. Deliver the requested text or file update, with supported claims and actionable migration details. Explicit user instructions take precedence over this guidance.

Scope and evidence

Use the requested version, range, audience, and destination. Infer missing context from the project's release conventions and available sources; ask only when ambiguity materially changes which release or changes the note covers. Keep an unknown release date or version explicitly unresolved in a draft.

For a full release, account for the changes in the exact base-to-target range, including compatibility, security, runtime requirements, and behavior changes. Group related work into reader-facing entries; keep internal-only changes out of the published note. Use commits, release fragments, contract diffs, and shipped artifacts as applicable. Inspect code or PR context where summaries leave consequential claims unclear. For a single entry or supplied draft, keep investigation scoped to that change.

For a first release, inspect the target tree and relevant history, including the initial commit. Distinguish merged work from what actually ships, including feature flags and platform restrictions. If artifacts contradict the history, report the discrepancy rather than assuming either describes the intended release completely.

Writing contract

• Follow the project's language, format, attribution, and issue-reference conventions. Lead with observable impact and prioritize breaking changes, security, deprecations, and changed behavior. Scale the introduction and categories to the material.
• Preserve exact versions, public symbols, routes, configuration keys, and advisory IDs. Link available evidence; quantify performance claims only when measurements support them.
• For breaking or action-requiring changes, give the old behavior, new behavior, affected users, and concrete migration steps. Include a code or configuration example when it resolves ambiguity. State when no action or replacement exists.
• Keep changes to the requested documentation. A writing request does not authorize publishing, tagging, changing CI, or executing migrations. Carry out external actions when the user has authorized them; prepare the complete content before any required approval.