Skip to content
0degrees.ai
Tooling

Using AI to Write Changelogs and Release Notes

How to use AI to turn raw git diffs and commit messages into clear, user-facing changelogs and release notes — without losing important context.

0degrees Team7 min read

A changelog is not a git log. That distinction matters more than it sounds. git log --oneline gives you a list of commits; a changelog tells users what changed, why it matters to them, and what they might need to do about it. The two look similar on the surface and are completely different documents in practice.

AI coding assistants are genuinely good at this translation work — but only when you give them the right inputs. Feed in raw commit messages and you get a slightly reformatted list of commit messages. Give the model the diff, the ticket context, and a clear sense of who the audience is, and you get something worth publishing.

Why changelogs fail without structure

The pathological changelog looks like this:

v2.3.1 — November 17, 2026
- fix: bug fix
- feat: new feature
- chore: update dependencies
- fix: another fix
- feat: add thing

That’s a lightly reformatted git log. It tells a user nothing they couldn’t get from checking out the repo themselves. The actual information — what broke, what it affects, what the new behavior is — is buried in the commit bodies (if it was written at all) or in the diff.

A good changelog entry answers three questions:

  1. What changed? The behavior, not the implementation.
  2. Who does this affect? Everyone? Only users of a specific API? Only self-hosted deployments?
  3. What do I need to do? Nothing? Update a config key? Migrate data?

AI can answer all three questions well — but it needs the evidence to work from.

The right inputs

The minimum viable set of inputs for a useful changelog:

The diff, not just the commit messages. Commit messages are written for the developer who made the change; the diff shows what actually changed. For breaking changes especially, the diff is the ground truth.

# Diff for a specific range
git diff v2.3.0..v2.3.1 -- src/

# Or for a single PR merged to main
git diff main...feature/settings-rework

Linked issue or ticket titles. If your commit messages reference tickets (fix: handle null user on login (#482)), pull the ticket titles. The ticket title is usually written in user-facing language even when the commit message isn’t.

The previous changelog entry. This is optional but useful — it gives the model a tone reference and prevents duplicate entries if you’re appending to an existing file.

The audience. Who reads this changelog? A technical team consuming an SDK has different needs than end users of a web product. State this explicitly in your prompt.

A prompt that works

Here’s a template that reliably produces usable output:

You are writing a changelog entry for version {{version}} of {{product name}}.

Audience: {{developer/end user/mixed — describe briefly}}

Changes to summarize:
<diff>
{{paste diff here}}
</diff>

Commit messages in this release:
{{git log output}}

Additional context:
{{Paste any ticket titles or PR descriptions}}

Format the changelog as:
- One section per category (Breaking Changes, New Features, Bug Fixes, Improvements, Deprecations)
- Omit categories with no entries
- Each bullet: one sentence describing the user-visible behavior change, not the implementation
- Note any action required from users (config changes, migration steps) explicitly
- Use past tense
- Do not include internal refactors, test changes, or dependency bumps unless they affect behavior

Previous changelog style reference:
{{paste 2-3 existing entries}}

The key constraints are “user-visible behavior change, not the implementation” and “do not include internal refactors.” Without those, the model will faithfully summarize every test file and every dependency bump.

Separating developer and end-user entries

Many projects maintain two different changelogs: one for developers consuming an API or SDK, and one for end users of the product. These require different language and different levels of detail.

For the same change — say, a new retry configuration option on an API client — the two entries look like:

Developer changelog (SDK consumers):

- Added `maxRetries` option to `ApiClient` constructor (default: 3).
  Pass `maxRetries: 0` to disable automatic retries entirely. The previous
  behavior (always retry up to 3 times) is preserved unless you opt out.

End-user changelog (product users):

- Improved reliability: the app now automatically recovers from brief
  network interruptions without showing an error.

If you need both, run two separate AI passes with two different audience prompts. Trying to generate both in one pass usually produces something that serves neither audience well.

Handling breaking changes

Breaking changes deserve extra care because a user who misses them can have their application silently fail or suddenly error. When a diff contains a breaking change, include a dedicated section at the top of the entry with explicit migration steps.

A good prompt addition for breaking change detection:

Additionally, identify any breaking changes in the diff — defined as:
- Removed or renamed public API methods, types, or configuration keys
- Changed parameter order or required parameters
- Changed return type or shape
- Changed default behavior in a way that existing code might rely on

For each breaking change, provide:
1. What was removed/changed
2. What replaces it (or that there is no replacement)
3. A one-line migration example showing the before/after

This gives the model a clear definition of “breaking” rather than leaving it to infer from context. Models trained on code have a tendency to downgrade breaking changes to “improvements” if the diff also adds a migration path — an explicit definition prevents that.

A lightweight CI workflow

If you tag releases in your CI pipeline, you can automate a first draft of the changelog as part of the release process. Here’s a minimal GitHub Actions pattern:

# .github/workflows/draft-changelog.yml
on:
  push:
    tags:
      - 'v*'

jobs:
  draft-changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate diff since last tag
        run: |
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
          if [ -n "$PREV_TAG" ]; then
            git diff "$PREV_TAG"..HEAD -- src/ > /tmp/release.diff
            git log "$PREV_TAG"..HEAD --oneline > /tmp/commits.txt
          else
            git diff HEAD~20..HEAD -- src/ > /tmp/release.diff
            git log HEAD~20..HEAD --oneline > /tmp/commits.txt
          fi

      - name: Draft changelog with Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python3 scripts/draft_changelog.py \
            --diff /tmp/release.diff \
            --commits /tmp/commits.txt \
            --version "${GITHUB_REF#refs/tags/}" \
            --output /tmp/draft_changelog.md

      - name: Create GitHub release with draft
        uses: softprops/action-gh-release@v2
        with:
          body_path: /tmp/draft_changelog.md
          draft: true

The release is created as a draft — it doesn’t publish until a human reviews and edits it. This is the right default: AI produces a first draft, a person confirms it before it reaches users. The goal is to eliminate the blank-page problem, not to remove human judgment from the loop.

Review before you ship

AI-generated changelogs need human review for three reasons.

False confidence about scope. The model summarizes what’s in the diff, but it can’t know what else was supposed to be in the release and isn’t. A missing bug fix that the team intended to include won’t appear in the diff — and therefore won’t appear in the changelog.

Tone calibration. The model matches the tone of your style reference, but style references are rarely perfect. A breaking change worded casually (“removed deprecated setUser method”) reads very differently to a user who relied on it than to the developer who wrote the removal.

Internal jargon. Diffs are full of internal identifiers, table names, function names, and class names. A model that hasn’t been told “users don’t know what a UserSettingsRow is” will sometimes include those internal identifiers in user-facing entries.

The review step should be quick — five minutes for a typical release. The AI draft exists so the reviewer is editing and approving, not generating from scratch. That’s a much lower-friction task.

Connecting this to your commit discipline

The quality of AI-generated changelogs is directly proportional to the quality of the commit messages the model is working from. A commit message like fix: handle null user on login (#482) gives the model something to work with. fix: wip gives it nothing.

If your team uses conventional commits (feat:, fix:, chore:, BREAKING CHANGE:), the model can automatically categorize entries. If commits are more freeform, you’ll spend more time in the review pass correcting miscategorizations.

The AI for Commits and Pull Requests post covers building that habit at the commit level. The payoff shows up at release time — a release with 30 well-formed commit messages produces a substantially better first-draft changelog than the same release with 30 fix: stuff entries.

What AI still can’t do well here

There are two things to watch for.

It can’t infer intent from silence. If a behavior changed but the commit message doesn’t say why, the model will describe the new behavior without the reason. That’s often fine for user-facing entries, but can frustrate developers who need to understand why an API shape changed.

It can flatten nuance about severity. A subtle performance regression that affects only large datasets looks the same in a diff as a minor copy tweak. The model weights by what it sees, not by what matters most to your users. The human reviewer’s job is to reorder and weight entries by impact before publishing.

Neither of these is a blocker — they’re just places to focus attention during review.

The workflow that works in practice: AI draft from diff and commits, five-minute human review to adjust tone and ordering, publish. That’s faster than writing from scratch and more accurate than a git log reformatter. For most projects, it’s the right trade-off.

[ Related ]

Keep reading