version: "1.0.0" name: release-notes description: "Generate release notes from commit history. Use when asked to draft release notes, create a changelog, or summarize changes for a release." source: "Internal engineering practices" domain: "documentation" level: "foundational" agents: ["orchestrator", "backend-dev"] created_date: "2026-04-27" last_validated: "" validated_by: "" status: "draft"

Release Notes

Overview

A structured process for generating release notes from commit history. Groups changes by type, highlights breaking changes, and produces user-friendly summaries.

Patterns & Techniques

Generation Process

Step 1: Gather changes

git log --oneline $(git describe --tags --abbrev=0)..HEAD

Step 2: Categorize using conventional commit prefixes:

• 🚀 Features (feat:)
• 🐛 Bug Fixes (fix:)
• 📚 Documentation (docs:)
• 🔧 Maintenance (chore:, refactor:)
• ⚠️ Breaking Changes (BREAKING CHANGE or !)

Step 3: Write using the template:

# Release vX.Y.Z
 
## Highlights
Brief summary of the most important changes (2-3 sentences).
 
## 🚀 Features
-Description of feature (#PR)
 
## 🐛 Bug Fixes
-Description of fix (#PR)
 
## ⚠️ Breaking Changes
-What changed and migration steps
 
## 📚 Documentation
-What was updated
 
## 🔧 Maintenance
-Internal changes

Step 4: Review

• All significant changes included
• PR/issue references correct
• Breaking changes include migration instructions

Common Pitfalls

• Listing commit messages verbatim — Rewrite for the reader, not the committer
• Missing breaking changes — Always call these out prominently with migration steps
• No highlights section — Users want a 2-sentence summary, not a raw list