# Release Notes Generator

> Create release notes that summarize features, fixes, and migration guidance for software releases.

- Skill: `stanfordspezi/release-notes-generator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stanfordspezi/release-notes-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stanfordspezi/release-notes-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: stanfordspezi (https://skillmd.com/u/stanfordspezi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stanfordspezi/release-notes-generator

---


<!--
This source file is part of the Stanford Spezi open-source project.
SPDX-FileCopyrightText: 2026 Stanford University and the project authors (see CONTRIBUTORS.md)
SPDX-License-Identifier: MIT
-->

# Release Notes Generator

Create release notes summarizing features, fixes, and breaking changes for releases.

## When to Use

Use this skill when you need to:
- Prepare release notes for a new version
- Summarize changes for users/stakeholders
- Document migration steps for breaking changes

Use `keep-a-changelog-generator` instead when you need to maintain the project's `CHANGELOG.md` file. This skill writes the narrative announcement for a single release; that one keeps the structured, cumulative changelog.

## Release Notes Structure

```markdown
# Release v1.2.0

## Highlights

Brief summary of the most important changes (2-3 sentences).

## New Features

### Feature Name
Description of what it does and why it matters.

**Usage:**
```typescript
// Code example
```

## Improvements

- Improvement 1
- Improvement 2

## Bug Fixes

- Fixed issue with X (#123)
- Resolved Y when Z

## Breaking Changes

### Change Name

**What changed:** Description

**Migration:**
```typescript
// Before
oldMethod();

// After
newMethod();
```

## Dependencies

- Updated `package-name` from 1.0.0 to 2.0.0
```

## Information Gathering

### Git Commands

```bash
# Commits since last release
git log v1.1.0..HEAD --oneline

# Detailed commit messages
git log v1.1.0..HEAD --format="%h %s%n%b%n---"

# Files changed
git diff v1.1.0..HEAD --stat

# Contributors
git log v1.1.0..HEAD --format="%an" | sort | uniq
```

## Writing Guidelines

### Highlights Section

Focus on user value:
- What can users do now that they couldn't before?
- What problems are solved?
- Why should they upgrade?

### Feature Descriptions

Include:
- What it does
- Why it matters
- Basic usage example

### Breaking Changes

Must include:
- Clear description of what changed
- Why it changed
- Step-by-step migration guide
- Code examples (before/after)

### Version Numbers

Follow semantic versioning:
- **Major (1.0.0)**: Breaking changes
- **Minor (0.1.0)**: New features, backward compatible
- **Patch (0.0.1)**: Bug fixes, backward compatible

## Example Release Notes

```markdown
# Release v1.2.0

## Highlights

This release adds health data visualization and improves task scheduling
performance. Users can now view their health trends over time.

## New Features

### Health Data Visualization

View your health metrics in interactive charts.

**Usage:**
```typescript
import { HealthChart } from './components/health';

<HealthChart data={healthData} timeRange="week" />
```

## Improvements

- Task scheduling is now 50% faster
- Improved error messages for authentication failures

## Bug Fixes

- Fixed race condition in account state initialization (#45)
- Resolved infinite loop when no tasks exist (#52)

## Breaking Changes

### useHealthData Hook

**What changed:** `useHealthData()` now returns an object instead of array

**Migration:**
```typescript
// Before
const [data, isLoading] = useHealthData();

// After
const { data, isLoading } = useHealthData();
```
```

## Checklist

- [ ] Highlights summarize key changes
- [ ] All new features documented with examples
- [ ] Breaking changes have migration guides
- [ ] Bug fixes reference issue numbers
- [ ] Version number follows semver