---
name: write-release-notes
description: Generate release notes and changelog entries from git history and project changes. Use when the user asks to write release notes, create changelog, document version changes, or generate release documentation.
tools: ["read_file", "write_file"]
---

# Write Release Notes

## Instructions

Generate professional release notes and changelog entries for software releases. Analyze project changes, git history, and version information to create comprehensive release documentation.

### Step 1: Gather Release Information

1. **Determine version information**:
   - Read `package.json`, `pyproject.toml`, `Cargo.toml`, or other version files
   - Check for version bumps or new version numbers
   - Identify if this is a major, minor, or patch release (semantic versioning)
   - Use `bash_command` to check version files: `cat package.json | grep version`

2. **Analyze git history**:
   - Use `bash_command` to get recent commits: `git log --oneline --since="2 weeks ago"` or `git log --oneline -20`
   - Use `bash_command` to get diff stats: `git diff --stat HEAD~10..HEAD`
   - Use `bash_command` to compare versions: `git log v1.0.0..HEAD --oneline` (if previous tag exists)
   - Look for conventional commit messages (feat:, fix:, docs:, etc.)

3. **Check for changelog files**:
   - Read existing `CHANGELOG.md`, `CHANGES.md`, or `RELEASE_NOTES.md` if they exist
   - Maintain consistency with existing format
   - Check for `CHANGELOG` or `HISTORY` files in project root

4. **Identify project type**:
   - Check for package managers: `package.json` (npm), `pyproject.toml` (Python), `Cargo.toml` (Rust)
   - This helps determine version format and release conventions

### Step 2: Categorize Changes

Organize changes into standard release note categories:

1. **Added** (Features):
   - New features, functionality, or capabilities
   - Look for: `feat:`, "add", "new", "introduce" in commit messages
   - Major new components or modules

2. **Changed** (Improvements):
   - Improvements to existing features
   - API changes (non-breaking)
   - Performance improvements
   - Look for: "improve", "enhance", "update", "refactor" in commits

3. **Fixed** (Bug Fixes):
   - Bug fixes and issue resolutions
   - Look for: `fix:`, "bug", "issue", "correct" in commit messages
   - Security fixes

4. **Deprecated**:
   - Features marked for removal
   - Look for: "deprecate", "deprecated" in commits or code comments

5. **Removed**:
   - Features or APIs removed
   - Look for: "remove", "delete", "drop" in commits

6. **Security**:
   - Security vulnerabilities fixed
   - Look for: "security", "CVE", "vulnerability" in commits

### Step 3: Analyze Commits and Changes

1. **Parse commit messages**:
   - Use `bash_command`: `git log --pretty=format:"%h - %s (%an, %ar)" -20`
   - Group by type using conventional commits or patterns
   - Extract meaningful descriptions

2. **Review code changes**:
   - Use `bash_command`: `git diff --stat HEAD~10..HEAD` to see file changes
   - Use `bash_command`: `git log --name-status --pretty=format:"" HEAD~10..HEAD` for changed files
   - Look at PR titles or commit descriptions for context

3. **Identify breaking changes**:
   - Look for: `BREAKING CHANGE:`, "breaking", "major", "incompatible" in commits
   - Check API changes in code
   - Review migration guides if they exist

### Step 4: Generate Release Notes Structure

Create a well-formatted release notes document with this structure:

```markdown
# Release Notes - Version X.Y.Z

**Release Date**: [Current date]
**Full Changelog**: [Link to full changelog if applicable]

## Summary

Brief 2-3 sentence summary of this release highlighting the most important changes.

## 🎉 Added

- [Feature description with context]
- [Another feature]

## ✨ Changed

- [Improvement description]
- [API change with migration notes if applicable]

## 🐛 Fixed

- [Bug fix description with issue reference if available]
- [Another fix]

## 🔒 Security

- [Security fix description]

## ⚠️ Breaking Changes

- [Breaking change description]
- [Migration guide reference or steps]

## 📚 Documentation

- [Documentation improvements]

## ⚙️ Internal

- [Internal improvements, refactoring, build changes]

## Contributors

Thank you to all contributors: [List of contributors if available from git log]

## Upgrade Instructions

[If applicable, provide upgrade/installation instructions]
```

### Step 5: Write Professional Release Notes

1. **Use clear, user-facing language**:
   - Avoid technical jargon where possible
   - Explain what changed and why it matters
   - Include examples or use cases for major features

2. **Be specific and actionable**:
   - "Fixed memory leak in data processing" not just "Fixed bugs"
   - "Added support for Python 3.12" not just "Updated Python support"
   - Include issue numbers or PR references if available

3. **Group related changes**:
   - Combine similar fixes or features
   - Use sub-bullets for detailed changes
   - Keep each category organized

4. **Include migration notes**:
   - For breaking changes, provide clear upgrade paths
   - Reference migration guides if they exist
   - Show before/after examples for API changes

5. **Add context**:
   - Link to relevant documentation
   - Reference related issues or PRs
   - Include contributor credits if appropriate

### Step 6: Format and Style

1. **Use markdown formatting**:
   - Headers for version and date
   - Bullet points for lists
   - Code blocks for examples
   - Links for references

2. **Consistent style**:
   - Start each item with a verb (Added, Fixed, Changed)
   - Use present tense or past tense consistently
   - Keep line lengths reasonable (80-100 chars)

3. **Emoji usage** (optional but helpful):
   - 🎉 for new features
   - ✨ for improvements
   - 🐛 for bug fixes
   - 🔒 for security
   - ⚠️ for breaking changes
   - 📚 for documentation

4. **Version format**:
   - Follow semantic versioning: `MAJOR.MINOR.PATCH`
   - Use consistent format: `v1.2.3` or `1.2.3`
   - Match project's existing versioning style

### Step 7: Handle Different Scenarios

#### First Release:
- Focus on initial features and setup
- Explain what the project does
- Include installation/setup instructions

#### Patch Release:
- Focus on bug fixes
- May not need full structure
- Quick summary format

#### Major Release:
- Include migration guide
- Highlight breaking changes prominently
- Provide upgrade checklist

#### No Git History:
- Use file changes detected via `list_directory` and `read_file`
- Analyze code modifications
- Create notes from current state vs expected state

### Step 8: Verify and Complete

1. **Check completeness**:
   - All significant changes included
   - No placeholder text remaining
   - Version number is correct
   - Date is current

2. **Validate format**:
   - Markdown renders correctly
   - Links work (if any)
   - Consistent style throughout

3. **Save appropriately**:
   - Save as `RELEASE_NOTES.md` or `CHANGELOG.md`
   - Or append to existing `CHANGELOG.md`
   - Follow project conventions

## Examples

### Example 1: Semantic Versioning Project
User: "Write release notes for version 2.1.0"
- Check `package.json` or `pyproject.toml` for version
- Analyze git commits since last tag
- Categorize into Added/Changed/Fixed
- Generate formatted release notes

### Example 2: Update Existing Changelog
User: "Update the changelog"
- Read existing `CHANGELOG.md`
- Get recent commits since last entry
- Add new entry at top
- Maintain existing format style

### Example 3: First Release
User: "Create release notes for the initial release"
- Analyze current project state
- List initial features from codebase
- Create comprehensive first-release notes
- Include installation instructions

## Best Practices

1. **Be accurate**: Only include changes that actually happened
2. **Be user-focused**: Write for end users, not just developers
3. **Be complete**: Include all significant changes
4. **Be concise**: Don't list every single commit, group intelligently
5. **Be helpful**: Provide context and upgrade instructions
6. **Follow conventions**: Match existing project style and format

## Tools to Use

- `bash_command`: Run git commands to analyze history
- `read_file`: Read version files and existing changelogs
- `list_directory`: Explore project structure
- `grep_search`: Find version numbers or change indicators in files

## Notes

- If git history is not available, focus on analyzing current code state
- Respect existing changelog format if one exists
- When unsure about a change, err on the side of inclusion
- Major releases should always include migration guides for breaking changes
- Security fixes should be clearly highlighted

