20.5 Changelogs and migration notes with AI assistance

Goal: release communication that’s accurate

Changelogs and migration notes are how users (and teammates) understand what changed and how to adapt.

For AI apps, this includes not only code changes but also:

• prompt version changes,
• schema version changes,
• model selection changes,
• behavior changes caused by new constraints.

Changelogs: what to include

A useful changelog includes:

• Added: new features
• Changed: behavior changes
• Fixed: bug fixes
• Deprecated/Removed: breaking changes

Keep entries concrete: “Added --repl mode” is better than “Improved UX.”

Migration notes: how to write them

Migration notes are required when changes break clients or workflows. Good migration notes include:

• what changed and why
• who is affected
• step-by-step upgrade path
• before/after examples (schemas, CLI flags, API payloads)
• rollback guidance (if possible)

Using AI to draft from diffs (safely)

AI is excellent at summarizing diffs into human-readable changes. Safe workflow:

• provide the diff or a structured summary of changes
• require that each changelog entry maps to something in the diff
• require the model to mark uncertain items as unknown
• review manually (AI may miss subtle breaking changes)

Copy-paste prompt

Draft a changelog entry based ONLY on this diff/summary:
(paste)

Rules:
- Do not invent changes not present in the diff
- Group into Added/Changed/Fixed/Deprecated
- Call out breaking changes explicitly
- If unsure, mark as unknown and ask a question

AI apps: include prompt/schema version changes

In AI apps, prompt and schema changes are behavior changes. Your changelog should record:

• prompt version bumps (e.g., summarize@v2) and what changed
• schema version bumps and field changes
• evaluation results if available (“reduced invalid_output rate from X to Y”)

This makes behavior changes auditable and debuggable.

Copy-paste templates

Template: changelog entry

## [Unreleased]

### Added
- ...

### Changed
- ...

### Fixed
- ...

### Deprecated
- ...

Template: migration note

# Migration: v1 → v2

Summary:

Who is affected:

Breaking changes:

Upgrade steps:
1) ...

Examples:
- Before: ...
- After: ...

Where to go next

• Part VII — Multimodal & long context
• Part IX — Testing and evaluation