Release notes generator

Generate release notes in 3 formats from git commits for production releases.

Process

1. Analyze Git History: Scan commits since last release tag
2. Fetch PR Details: Get titles, descriptions via gh api
3. Categorize Changes: Group by type (feat, fix, perf, etc.)
4. Check Migrations: Detect database migration files
5. Generate 3 Outputs: CHANGELOG, PR body, communication message
6. Transform Language: Convert tech jargon to product language

Output formats

1. CHANGELOG.md Section

## [X.Y.Z] - YYYY-MM-DD

### Summary
[1-2 sentence overview of this release]

### New Features
#### [Feature Name] (#PR)
- **Description**: User-facing functionality added
- **Impact**: How it benefits users

### Bug Fixes
- **[Module]**: Description (#issue, tracking-ID)

### Technical Improvements
- [Internal improvements, refactoring, performance]

### Database Migrations
[If applicable - list migration files]

### Statistics
- PRs: X | Features: Y | Fixes: Z | Files changed: N

2. PR release body

Uses your project's release template:

• .github/PULL_REQUEST_TEMPLATE/release.md
• .github/pull_request_template_release.md
• Or custom location specified in project config

3. Communication announcement

Generate user-facing announcement (Slack, email, etc.):

• Non-technical language
• Focus on user impact
• Readable formatting (emojis optional)

Template location examples:

• .github/COMMUNICATION_TEMPLATE/slack-release.md
• docs/templates/release-announcement.md

Migration alert

If migrations detected:

╔══════════════════════════════════════════════════════════════════╗
║  ⚠️  [ATTENTION] DATABASE MIGRATIONS REQUIRED                    ║
╠══════════════════════════════════════════════════════════════════╣
║  This release contains X migration(s):                           ║
║  • 20250110_add_user_preferences                                 ║
║  • 20250112_create_audit_log_table                               ║
║  Action required: Run migration command after deployment         ║
╚══════════════════════════════════════════════════════════════════╝

If no migrations:

✅ [OK] No database migrations required

Tech-to-product transformation

Convert technical commits to user-friendly descriptions:

Technical	Product/User Language
"Optimize N+1 queries with DataLoader"	"Faster loading times for lists"
"Implement AI embeddings with pgvector"	"New intelligent search feature"
"Fix permissions scope bug"	"Resolved access issue for certain users"
"Migration webpack -> Turbopack"	Internal only - don't communicate
"Refactor React hooks architecture"	Internal only - don't communicate
"Add rate limiting to API endpoints"	"Improved system stability and security"

Commit categories

Prefix	Category	Include in Announcement?
feat:	New Features	Yes
fix:	Bug Fixes	Yes (if user-facing)
perf:	Performance	Yes (simplified)
security:	Security	Yes
refactor:	Architecture	No
chore:	Maintenance	No
docs:	Documentation	No
test:	Tests	No
build:	Build System	No
ci:	CI/CD	No

Commands to execute

# 1. Get last release tag
LAST_TAG=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)

# 2. List commits since tag (excluding merges)
git log $LAST_TAG..HEAD --oneline --no-merges

# 3. Get commit details with PR numbers
git log $LAST_TAG..HEAD --format="%h %s" --no-merges

# 4. Check for migrations (adjust path to your ORM)
# Prisma:
git diff $LAST_TAG..HEAD --name-only -- prisma/migrations/
# Sequelize:
git diff $LAST_TAG..HEAD --name-only -- migrations/
# Django:
git diff $LAST_TAG..HEAD --name-only -- '**/migrations/*.py'
# Alembic:
git diff $LAST_TAG..HEAD --name-only -- alembic/versions/

# 5. Get PR details via GitHub CLI
gh api repos/{owner}/{repo}/pulls/{number}

# 6. Count statistics
TOTAL_PRS=$(git log $LAST_TAG..HEAD --oneline --merges | wc -l)
FEATURES=$(git log $LAST_TAG..HEAD --oneline --no-merges | grep -c 'feat:')
FIXES=$(git log $LAST_TAG..HEAD --oneline --no-merges | grep -c 'fix:')

Semantic versioning

Determine version number based on changes:

Change Type	Version Bump	Example
Breaking change	MAJOR (X.0.0)	API removed, incompatible change
New feature	MINOR (0.X.0)	New functionality, backward-compatible
Bug fix / patch	PATCH (0.0.X)	Bug fixes only

Indicators:

• BREAKING CHANGE: in commit body → MAJOR
• feat: commits present → MINOR
• Only fix: / perf: → PATCH

Workflow integration

Typical release workflow:

1. Verify all PRs merged to develop branch
2. Run: /release-notes (or specify version/range)
3. Review generated outputs for accuracy
4. Create PR: develop -> main with "release" label
5. Add generated CHANGELOG section to CHANGELOG.md
6. Use generated PR body as PR description
7. After merge: Create and push git tag
8. Post communication announcement (Slack/email/etc.)
9. Monitor deployment and migrations

Git tag creation

After PR merge, create annotated tag:

# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3: Brief description"

# Push tag to remote
git push origin v1.2.3

# Or push all tags
git push --tags

Project-specific customization

Adapt these paths to your project:

# Migration detection (adjust ORM path)
prisma/migrations/        → Your ORM migration directory
db/migrate/               → Rails migrations
alembic/versions/         → Alembic migrations

# Template files (create if needed)
.github/PULL_REQUEST_TEMPLATE/release.md
.github/COMMUNICATION_TEMPLATE/announcement.md
docs/templates/release-notes.md

Tips

• Run from repository root: Ensures git commands work correctly
• Authenticate GitHub CLI: Run gh auth login if needed
• Review before publishing: Always verify generated content
• Breaking changes: Search commit messages for BREAKING CHANGE:
• Linked issues: Include issue/ticket numbers for traceability
• Database migrations: Test in staging before production

Edge cases

Scenario	Behavior
No tags found	Start from first commit
No commits since last tag	Error: "No changes to release"
Multiple tags on same commit	Use most recent by date
Pre-release tags (v1.0.0-beta.1)	Exclude from "last release" search
Commits without conventional format	Categorize as "Other Changes"

Usage examples

# Generate release notes from last tag to HEAD
/release-notes

# Specify version manually
/release-notes v1.5.0

# Specify range
/release-notes from v1.4.0 to HEAD

# Preview without creating files
/release-notes --preview

# Include pre-release commits
/release-notes --include-pre-release

Version/Range: $ARGUMENTS