---
name: writing-release-notes-from-git-diffs
description: Draft clear, accurate release notes from raw git diffs, merged PRs, commit ranges, tags, changelog fragments, or auto-generated notes. Use this skill whenever the user asks for release notes, a changelog, version highlights, upgrade notes, breaking changes, launch notes, “what changed” summaries, or wants raw technical changes rewritten for users, customers, admins, or developers. Also use it when the input is noisy PR metadata or diffs and the job is to turn that into concise human-facing notes without overclaiming.
---

^{[1] [1]}

Writing Useful Release Notes from Git Diffs

Turn technical change input into release notes a reader can scan and trust.

Release notes are for humans, not machines. Keep user-facing and upgrade-relevant changes, and do not dump raw commit logs into the final notes.^[6][2]

Rewrite implementation detail into user-visible outcome, make upgrade risk obvious, and keep the wording within what the diff, PR text, changelog fragments, and linked docs actually prove.^[2][3][4][5]

Quick guidance

1. Lock the release scope before summarizing anything. Confirm the exact tag or comparison range, and if generated notes are involved, name the previous tag explicitly instead of trusting an auto-selected range.^[11][4][12]
2. Gather all available evidence for that range: merged PRs or MRs, labels, commit titles, changelog fragments or trailers, linked docs, migration notes, and the diff for unclear items.^[4][5]
3. Keep only user-facing, API-facing, security-relevant, migration-relevant, or operator-relevant changes. Drop refactors, tests, CI cleanup, docs-only edits, experiments, and regressions introduced and fixed within the same unreleased cycle unless the user asked for an internal engineering log.^[2][7]
4. Rewrite each kept item as a user-visible result. Start bullets with imperative present-tense verbs such as Add, Improve, Fix, Prevent, Deprecate, or Remove.^[2][7]
5. Group the final notes into stable sections such as Added, Changed, Deprecated, Removed, Fixed, Security, and Performance when relevant.^[6][5]
6. Break out breaking changes and upgrade instructions into their own section whenever compatibility risk exists.^{[3][6][9][10]}
7. Match detail to the audience. End-user notes should favor plain language; developer and operator notes should name exact config keys, flags, version constraints, defaults, prerequisites, and migration actions when those details matter.^[1][7][8]
8. Do not overclaim. If the available inputs do not prove a user-visible benefit, describe the technical change narrowly or omit it.^[2][6][3]

Workflow

1. Lock the scope

Identify the exact release range first. Prefer explicit tags or a named previous release over vague time windows. If the user did not provide the range, ask for it or state the assumed range in the notes.^[11][4][12]

2. Collect the best evidence

• Merged PRs or MRs
• Labels and categories
• Commit titles
• Changelog trailers or fragments
• Docs, migration guides, or upgrade notes linked from the PRs
• The diff when the user-facing effect is unclear

Use labels as grouping hints, not as proof of impact. GitHub categories depend on repository configuration, exclusions, and catch-all rules, so autogenerated notes are a draft input rather than a canonical summary.^[4][12]

3. Filter for what belongs

Keep changes that affect users, customers, client developers, operators, or administrators. Include new features, bug fixes with visible effects, performance changes users may notice, security fixes, API changes, configuration changes, deprecations, removals, and migrations.^[2][6]

Exclude refactors, technical-debt cleanup, test-only changes, build or CI cleanup, internal tooling, docs-only edits that do not reflect a shipped behavior change, experiments, and regressions introduced and fixed within the same release cycle.^[2][7]

4. Rewrite from mechanism to outcome

Write for a zero-context reader. If a short bullet becomes too vague, add context about where the change appears or what broke, but do not fall back into implementation detail.^[2]

Prefer the result over the mechanism.

• Bad: Refactor cache invalidation around search index sync.
• Better: Fix stale search results after bulk updates.
• Bad: Add support for config-driven retry backoff via new parser path.
• Better: Add configurable retry backoff for failed webhook deliveries.

5. Organize the notes

Use Added, Changed, Deprecated, Removed, Fixed, Security, and Performance as the default sections unless the project already has a stronger house style. Collapse sparse sections when the release is small. Split by product area when the release is broad.^[6][5][9][4]

6. Isolate breaking changes and upgrade notes

Never bury breaking changes inside ordinary feature bullets. Create a dedicated section such as Breaking Changes, Backwards Incompatible Changes, Potentially Breaking Changes, or Upgrade Notes.^[3][6][9]

For each risky change, state what changed, who is affected, what is incompatible, what action is required, and where to find more detail. If the change replaces or removes something, name the old thing, the replacement, and the required upgrade action.^[3][14]

7. Add explicit upgrade guidance when behavior changes

When defaults, config keys, supported versions, API behavior, or migration assumptions change, add concrete upgrade guidance. Name the old behavior, the new behavior, prerequisites, whether the change is enabled by default, and the migration steps when known.^[8][10]

8. Match the level of detail to the reader

For end-user product notes, prefer plain language and emphasize visible behavior. For developer notes, name endpoints, fields, methods, flags, and version constraints precisely. For admin or operator notes, emphasize defaults, rollout prerequisites, migration steps, compatibility caveats, and rollback considerations.^{[1][7][8][13]}

Output recipe

Use this default shape unless the project already has a better established format.^[9][8][4]

1. Optional one-sentence release summary
2. Highlights for the most important user-facing changes
3. Categorized change list
4. Breaking Changes or Upgrade Notes if needed
5. A brief scope note only when the provided inputs are partial and that limitation matters

Keep bullets parallel. Start each bullet with a strong verb. Prefer one concrete claim per bullet. In operator-facing or rollout-heavy releases, include prerequisites, rollout status, caveats, or fallback actions when the source material supports them.^{[7][2][8][13]}

If the source set is incomplete, add a short scope note only when the gap changes how the notes should be read. Keep the caveat specific to the missing evidence instead of adding boilerplate.^[12][1][4]

Worked examples

Example 1: Rewrite low-level PRs into user-facing notes

Input

• Range: v2.3.0...v2.4.0
• PR #481: Refactor webhook retry scheduler and add exponential backoff parser
• PR #492: Fix nil deref when org slug missing in invite acceptance flow
• PR #500 label: breaking-change
• Diff shows old config retry_delay_ms replaced by webhook.retry.initial_delay and webhook.retry.max_delay
• Changelog fragment: added

Output

## Highlights
- Add configurable retry backoff for failed webhook deliveries.
- Fix a crash when accepting an invitation with a missing organization slug.
## Changed
- Add `webhook.retry.initial_delay` and `webhook.retry.max_delay` to control webhook retry timing.
## Breaking Changes
- Replace `retry_delay_ms` with `webhook.retry.initial_delay` and `webhook.retry.max_delay`. Update existing configuration before upgrading or webhook delivery settings may no longer load as expected.

This rewrite keeps the proven crash fix, removes refactor language, and names the exact configuration keys users must update.^[2][7][3]

Example 2: Infrastructure-style notes with upgrade caveats

Input

• Range: 1.8.0...1.9.0
• PR #2101: nftables backend beta default on
• PR #2110: docs: migration guide for iptables users
• PR #2122: linux kernel gate check >= 5.13
• PR #2140: plugin compatibility follow-up

Output

## Highlights
- Enable the nftables backend by default in beta for Linux clusters.
## Upgrade Notes
- The nftables backend is available only on Linux nodes and requires kernel 5.13 or later.
- Some network plugins may not yet be compatible with nftables mode.
- NodePort behavior is not identical to iptables mode in all cases. Review the migration guide before switching existing clusters.
## Changed
- Add beta support for the nftables backend with Linux and kernel-version prerequisites.

This rewrite keeps the compatibility and migration facts operators need without inventing benefits that the raw inputs do not prove.^[8][14]

Example 3: Generated notes are a starting draft, not the final answer

Input

• GitHub draft release generated from merged PRs between v4.6.0 and v4.7.0
• Section labels map enhancement to New Features and breaking-change to Breaking Changes
• Unlabeled PR: Return 409 instead of 500 when duplicate API token name is submitted
• Labeled PR: enhancement — Remove legacy token create endpoint
• Migration note linked from PR: clients must switch to POST /v2/tokens

Output

## Highlights
- Improve duplicate token creation errors by returning a conflict response instead of an internal server error.
## Breaking Changes
- Remove the legacy token creation endpoint. Update clients to use `POST /v2/tokens` before upgrading.
## Fixed
- Return HTTP 409 for duplicate token names instead of HTTP 500.

This rewrite overrides a misleading label, preserves the uncategorized user-facing fix, and converts raw API details into upgrade-ready notes.^{[4][12][3][2]}

Gotchas

• Do not publish raw commit subjects or autogenerated notes unchanged unless the user explicitly wants an internal engineering log.^[6][12]
• Do not let labels decide meaning when the diff, changelog fragment, or migration note says otherwise.^[4][2]
• Do not hide breaking changes under Added or Changed. Put them in a section that readers cannot miss, and include the action they need to take.^[3][6][14]
• Do not claim speed, reliability, security, usability, or business impact unless the source material proves that outcome.^[2][6][3]
• Do not omit exact config keys, flags, endpoints, version requirements, defaults, or prerequisites when readers must act on them.^[7][8][10]
• Do not turn unreleased churn into a headline. Experiments and regressions introduced and fixed inside the same unreleased cycle usually do not belong.^[2]
• Do not force every release into the same number of sections. Small releases can be short if the important changes are still easy to find.^[1][9][4]

Final check before answering

• Make the version range explicit.
• Include only user-facing or upgrade-relevant items.
• Phrase each bullet as what changed for the reader, not what the author refactored.
• Make breaking changes and deprecations easy to spot.
• Name exact keys, flags, endpoints, versions, defaults, or prerequisites when readers must act.
• Stay within what the diff, PRs, changelog fragments, and linked docs support.
• Add a scope caveat only when the inputs are materially incomplete.
• Match the level of detail to the audience.

Use imperative instructions, keep the body compact, and rely on worked examples to show the pattern rather than encoding brittle rules for every edge case.^[1]