To write release notes from code changes with AI, freeze the previous and current release boundaries, build a verified change ledger, and state user impact separately from implementation detail. Give AI only approved evidence and require every note to map back to a pull request, commit, issue, test, or document. A release owner must verify the final text against the shipped artifact.

This workflow produces user-facing release communication, not a commit digest. The guide to using AI covers safe inputs, while AI for coding and reviewing AI-generated code cover implementation work. Release notes begin after the change boundary and evidence are known.

Key Takeaways

Freeze exact previous and current tags or commits before drafting.

Build a ledger that distinguishes code evidence from verified user impact.

Do not infer behavior from filenames, diff size, or commit titles.

Classify changes consistently as added, changed, fixed, security, deprecated, or removed.

Keep migrations, known issues, and disclosure limits explicit.

Require release owner approval against the actual artifact and version.

Freeze the release boundary

Identify the exact artifact being described and the exact artifact it replaces. Record repository, product or component, previous version or commit, current version or commit, build identifier, target channel, and release date. A branch name such as main is not a stable boundary because it can move while drafting.

Use an immutable tag or full commit identifier when possible. If multiple repositories contribute to one release, record a boundary for each and identify the composition manifest or build record that connects them. If the deployed artifact does not match the planned tag, stop and resolve the mismatch.

GitHub Releases associate notes and assets with a tag and can distinguish a release from ordinary repository history.［2］ GitHub can also generate release notes from merged pull requests and contributors between tags.［1］ These features are useful inputs, but they do not by themselves prove which behavior reached users or whether a pull-request title describes it accurately.

Freeze acceptance criteria too. Define the audiences, supported upgrade paths, distribution channels, and what counts as user-visible. An internal refactor may be excluded; a changed default, new permission, removed field, or operational requirement may be essential even if the diff is small.

Build a verified change ledger

Create one row per candidate note before writing prose. Use this template:

Version	Commit range	PR or commit	Related issue	User-visible behavior	Breaking	Migration	Security	Deprecation	Test evidence	Documentation	Owner
`x.y.z`	`[base..head]`	`[immutable ID]`	`[issue ID]`	`[verified behavior]`	Yes/No/Unknown	`[steps or none]`	Public/Private/None/Unknown	`[timeline]`	`[command and result artifact]`	`[page]`	`[name]`

Populate the PR or commit and Related issue from repository records, but verify the result in code, tests, documentation, or the built product. A merged proposal may have been partially reverted. An issue may describe the original problem rather than the final solution.

User-visible behavior should answer: who notices, under what conditions, what changed, and what they should do. “Refactored cache layer” is implementation detail. “Repeated requests now reuse a valid cached result for five minutes” is a behavior claim that still needs evidence.

Test evidence must identify the command, environment, relevant output, and date. “Tests passed” is not enough if nobody can tell which tests, which commit, or whether failures were skipped. Keep environment gaps visible; local success is not production proof.

How do you determine user impact from evidence?

Read the actual diff, changed contracts, migrations, configuration, feature flags, and documentation. Trace entry points and call sites when a change affects behavior indirectly. For data or API changes, inspect compatibility, default values, serialization, and upgrade order.

Do not infer behavior from filenames. A file named fix_login.py does not prove login is fixed. A large diff may only reformat generated code, while a one-line default change may alter every request. Commit titles and labels are indexing aids, not evidence.

For each candidate note, require at least one behavior-level source: an acceptance test, a reproduced before-and-after result, an approved specification, an observable contract change, or a manual verification record. Link implementation evidence as support, but do not substitute it for the user claim.

If behavior remains unverified, mark it Unknown and omit it from public notes until resolved. Do not turn developer expectation into customer fact. A planned feature behind a disabled flag is not generally available.

How should changes be classified consistently?

Use a controlled taxonomy:

Added: a newly available user capability.
Changed: an existing behavior, default, workflow, or requirement changed.
Fixed: a verified defect no longer reproduces under stated conditions.
Security: a security-relevant change handled under the disclosure policy.
Deprecated: something remains available but has a removal or replacement path.
Removed: something is no longer available.

Keep categories separate from semantic version decisions. Semantic Versioning defines major, minor, and patch changes for a declared public API, including incompatible changes and backward-compatible functionality or fixes.［3］ A product can use a different scheme, but it should document what version numbers promise.

Do not call a change “breaking” only because many files changed. Inspect public contracts, persisted data, configuration, automation, supported clients, and operational procedures. Conversely, a new required field or changed default may be breaking even if compilation succeeds.

Deprecation notes need the affected interface, replacement, first deprecated version, expected removal version or condition, and migration guidance. “Deprecated old endpoint” without a path forward is not useful.

Write release notes from code changes with AI using an evidence packet

Prepare a bounded packet containing the release boundary, approved ledger rows, audience and style guide, prior terminology, and required output structure. Exclude secrets, credentials, private customer data, sensitive logs, embargoed vulnerability detail, and irrelevant source code.

Do not give AI an unrestricted repository and ask “What changed?” A model may overweight readable files, miss generated or configured behavior, or infer intent from names. Humans and deterministic tools should establish the ledger first.

A reusable prompt is:

Draft release notes using only approved ledger rows. Preserve the exact version, audience, conditions, migration steps, known limitations, and evidence IDs. Do not infer behavior from filenames, commit titles, labels, or diff size. Do not claim a fix unless the row contains verification evidence. Separate Added, Changed, Fixed, Upgrade/Migration, Known Issues, and the Security Disclosure Boundary. If user impact is Unknown, omit the claim and list the evidence gap for the release owner.

Ask for a traceability table before prose:

Note ID	Draft statement	Ledger rows	Audience	Required action	Verification status
RN-01	`[bounded user-facing statement]`	CH-04	Administrators	`[step or none]`	Verified

Reject notes that combine unrelated rows or broaden scope. “Improved reliability” may not follow from one fixed edge case. “Faster” needs a defined metric and measured comparison.

How do you write for users rather than the diff?

Lead with outcomes the intended reader can recognize. Name the affected feature, condition, and required action. Avoid internal class names unless they are part of a supported public interface.

Prefer “Exports now preserve the selected timezone when reopened” over “Updated serializer timezone handling.” For fixes, describe the prior symptom and the condition in which it no longer occurs. Do not reveal unnecessary exploitation detail or promise that all related failures are impossible.

Use this structure:

Highlights: a small set of material, verified outcomes.
Changes: added, changed, deprecated, and removed behavior.
Fixes: verified defects and their bounded conditions.
Upgrade/Migration: prerequisites, order, backup, and verification.
Known Issues: confirmed limitations and safe workarounds.
Security Disclosure Boundary: what can be stated now and where approved advisories will appear.

Not every release needs every section. Keep empty categories out of the public note, but retain their review status in the ledger so absence is deliberate rather than accidental.

Verify upgrades and migrations

Migration notes should be executable. State who must act, from which versions, in what order, with which permissions, and how to confirm success. Include backup and rollback guidance only when it is tested and supported.

Distinguish an application migration from a database migration, configuration rename, client upgrade, or operational restart. If old and new versions coexist during rollout, explain compatibility constraints. If the safe order is unknown, stop publication and obtain owner guidance.

Never fabricate a rollback. Some data transformations are irreversible, and some security changes should not be rolled back casually. State the approved recovery path and escalation contact rather than inventing a reassuring command.

Use AI-assisted test generation only as a separate reviewed engineering activity. Generated tests are not evidence until they run against the frozen revision and someone checks that they exercise the claimed behavior.

How much security detail belongs in public release notes?

Coordinate security wording with the responsible security and release owners. A public note may say that dependencies or protections were updated, but detailed vulnerability information may need an advisory, coordinated disclosure date, or customer-specific communication.

Do not paste secrets, exploit steps, private reports, or unannounced vulnerability details into an external model. Do not let AI decide severity, exploitability, affected versions, or disclosure timing. Those are evidence-heavy decisions owned by accountable people.

NIST’s Generative AI Profile highlights risks including confabulation, privacy, information integrity, and human oversight.［4］ A bounded evidence packet, claim-level traceability, access control, and release owner approval directly address those risks here.

The Security Disclosure Boundary section should state what the public note intentionally includes, what is deferred to an approved advisory, and who authorized that split. Silence should not accidentally imply that no security-relevant work occurred.

Review against the artifact

Review the draft line by line against the exact release artifact, not merely the source branch. Confirm version strings, feature flags, bundled dependencies, migration files, documentation links, and supported platforms. If packaging can exclude a change, verify the package.

Run this checklist:

base and head identifiers match the artifact;
every note maps to approved ledger rows;
user-visible behavior is demonstrated, not inferred;
version and category labels follow the product policy;
migration steps, order, and recovery are verified;
known issues include only confirmed limitations;
security wording follows the disclosure decision;
tests name actual commands, environments, and results;
links and version-specific documentation resolve locally;
the release owner approved the exact final text.

Release owner approval is required because the owner understands packaging, rollout, and disclosure context. The author or model cannot infer that context from a diff alone.

Maintain notes after publication

Archive the approved ledger, prompt inputs, draft, and final note with the release record. If a claim is corrected, publish a dated correction rather than silently rewriting history. Preserve what changed and why.

When a new commit enters the release, the original boundary is invalid. Regenerate the candidate ledger for the new range, identify added and affected notes, rerun verification, and obtain approval again. Do not append a guessed sentence to an already-reviewed draft.

Review feedback after release. Questions may reveal unclear migration steps, missing conditions, or terminology users do not recognize. Improve future templates, but keep each historical note tied to its shipped version.

FAQ

Can AI generate release notes directly from Git history?

It can create a candidate list, but history alone does not prove user impact or shipped behavior. Build and verify a change ledger before public drafting.

Are automatically generated GitHub release notes enough?

They are useful for enumerating merged work between tags. A release owner still needs to verify the artifact, audience, behavior, migrations, known issues, and disclosure boundaries.

Should every commit appear in release notes?

No. Include material user-visible behavior and required operational action. Preserve internal traceability separately for audit and debugging.

How do I describe a bug fix safely?

Name the observed symptom, affected condition, and verified outcome. Avoid claiming that an entire class of problems is impossible unless evidence supports that scope.

What if a change has no test?

Use another approved behavior-level verification or mark it unverified. Do not present developer intent as a confirmed release outcome.

Can AI choose the semantic version?

It can organize evidence against a documented policy, but the release owner must decide whether public contracts changed and approve the version.

Should security fixes be listed?

Follow the approved disclosure process. Public wording, timing, affected versions, and technical detail require security and release-owner review.

What happens if the commit range changes?

Freeze the new range, rebuild affected ledger rows, recheck every note, and obtain approval again. The earlier draft no longer describes the exact artifact.

Sources

GitHub Docs, Automatically generated release notes — https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
GitHub Docs, About releases — https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
Semantic Versioning 2.0.0 — https://semver.org/
National Institute of Standards and Technology, Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile — https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence

Sources checked 30 August 2026.

How to Write Release Notes from Code Changes with AI