Create Release Notes

Overview

Generate clear, user-facing release notes from git history and PR descriptions between two versions. Translate technical changes into language that users and stakeholders understand, grouped by impact category with breaking changes prominently highlighted.

Workflow

1. Read project context — Check .chalk/docs/ for:

- Previous release notes (to match tone, format, and conventions) - Product docs (to understand user-facing terminology) - Architecture docs (to map technical changes to user-facing features)

1. Determine the version range — From $ARGUMENTS:

- If two versions are provided (e.g., v1.1.0...v1.2.0), use that range - If only a target version is provided, find the previous tag: git tag --sort=-v:refname | head -5 - If no versions given, use the latest tag to HEAD: git log <latest-tag>..HEAD - Run git log --oneline --no-merges <from>..<to> to list all commits

1. Gather change details — For each commit in the range:

- Read the commit message (subject and body) - If a PR number is referenced, read the PR description for richer context - Identify the type of change: feature, improvement, bugfix, breaking change, deprecation, internal/chore - Skip purely internal changes (CI config, dev tooling) unless they affect the user

1. Classify changes — Group each change into one of these categories:

- Breaking Changes: API contract changes, removed features, changed defaults, required migration steps - New Features: Entirely new capabilities that did not exist before - Improvements: Enhancements to existing features (performance, UX, expanded functionality) - Bug Fixes: Corrections to incorrect behavior - Deprecations: Features or APIs that still work but will be removed in a future version - Security: Vulnerability patches and security improvements

1. Translate to user-facing language — For each change:

- Replace technical jargon with user-facing terms ("refactored the query builder" becomes "improved search performance") - Focus on the benefit to the user, not the implementation detail - Keep each entry to 1-2 sentences - Use active voice and present tense ("Adds dark mode support" not "Dark mode support has been added") - If the change is not user-facing, omit it from the notes (or group under "Internal" if the audience includes developers)

1. Write breaking changes section — For each breaking change:

- Clearly state what changed and why - Provide before/after examples - Include step-by-step migration instructions - Note the minimum version required for the migration - If an automated migration tool exists, reference it

1. Determine the next file number — List files in .chalk/docs/product/ matching releasenotes. Find the highest number and increment by 1.

1. Write the release notes — Save to .chalk/docs/product/<n>releasenotes_<version>.md.

1. Confirm — Present a summary: version, number of changes by category, any breaking changes that need attention.

Filename Convention

<number>_release_notes_<version>.md

Examples:

• 3releasenotesv12_0.md
• 8releasenotesv20_0.md

Release Notes Format

# Release Notes: <version>

**Release date**: <YYYY-MM-DD>
**Previous version**: <version>

## Highlights

<1-3 sentences summarizing the most important changes in this release. What should users be excited about or aware of?>

## Breaking Changes

> **Action required**: The following changes may require updates to your code or configuration.

### <Change title>

<What changed and why.>

**Before (<previous version>)**:
```<language>
<old code or configuration>

After (<this version>): ```<language> <new code or configuration>

**Migration steps**:
1. <Step-by-step migration instruction>
2. <Next step>

## New Features

- **<Feature name>** — <1-2 sentence description of what it does and why it matters to the user>
- **<Feature name>** — <description>

## Improvements

- **<Improvement area>** — <What got better and how it benefits the user>
- **<Improvement area>** — <description>

## Bug Fixes

- Fixed an issue where <user-visible symptom>
- Fixed <specific scenario> that caused <user-visible problem>

## Deprecations

- **<Deprecated feature>** — <What is deprecated, what to use instead, when it will be removed>

## Security

- Patched <brief, non-exploitable description> (severity: <level>)

---

**Full changelog**: `git log <from>..<to>`

Translation Guidelines

Technical to User-Facing

Tone and Style

• Do: Use plain language, focus on benefits, be specific about improvements
• Do: "Search results now load 50% faster" (specific, measurable)
• Do not: "Optimized the Elasticsearch query aggregation pipeline" (technical jargon)
• Do not: "Various bug fixes and improvements" (vague, unhelpful)
• Do: Use consistent verb tense (present tense: "Adds...", "Fixes...", "Improves...")
• Do not: Mix tenses ("Added...", "Fixes...", "Will improve...")

Audience Considerations

Anti-patterns

• Internal jargon — "Refactored the middleware pipeline" means nothing to users. Translate every entry into language your audience understands. If you cannot explain the user benefit, the change might not belong in release notes.
• Just listing commits — Copy-pasting git log output is not release notes. Commits are written for developers reviewing code, not for users understanding what changed. Synthesize, group, and translate.
• Not highlighting breaking changes — Burying a breaking change in a list of bug fixes causes users to miss it, leading to broken integrations and angry support tickets. Breaking changes get their own section, at the top, with migration instructions.
• Missing migration instructions — Saying "the API changed" without showing before/after examples and step-by-step migration is not actionable. Users need to know exactly what to change in their code.
• Vague entries — "Various improvements" and "bug fixes" tell the user nothing. If it is worth mentioning, be specific. If it is not worth being specific about, omit it.
• Including internal changes — CI pipeline updates, dev dependency bumps, and code formatting changes are not user-facing. Including them adds noise and makes real changes harder to find.
• No highlights section — Users scan release notes quickly. Without a highlights section, the most important changes get buried. Lead with what matters most.
• Inconsistent categorization — A performance improvement listed under "Bug Fixes" or a new feature listed under "Improvements" confuses users. Use the categories consistently and correctly.