Changelog & Release Notes Writer

Generate professional changelogs and release notes from version control history.

Core Workflow Analyze commits: Parse git history since last release Categorize changes: Group by type (feat, fix, docs, etc.) Identify breaking changes: Flag incompatible changes Extract highlights: Surface most important changes Format document: Follow Keep a Changelog format Suggest version: Recommend semantic version bump Generate release notes: Create user-friendly summary Commit Analysis Extract Information From Commit messages (preferably conventional commits) PR titles and descriptions Issue references (#123) Merge commit messages Commit authors Parse Patterns feat(auth): add OAuth2 support ^ ^ ^ | | └─ Description | └─ Scope (optional) └─ Type

Types to Categories:

feat → Added fix → Fixed docs → Documentation style, refactor → Changed perf → Performance test → Testing chore, ci → Internal BREAKING CHANGE → Breaking Changes Changelog Format (Keep a Changelog)

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• New feature X
• Support for Y

Changed

• Updated Z behavior

Fixed

• Resolved issue #123

2.1.0 - 2024-01-15

Added

• OAuth2 authentication support
• User profile management API
• Dark mode toggle

Changed

• Improved error messages
• Updated dependencies to latest versions

Deprecated

• Legacy authentication method (will be removed in 3.0.0)

Fixed

• Memory leak in WebSocket connection
• Incorrect date formatting in reports
• Race condition in concurrent requests

Security

• Patched XSS vulnerability in user input

2.0.0 - 2023-12-01

Breaking Changes

• ⚠️ Removed support for Node.js 16
• ⚠️ Changed API response format for /users endpoint
• ⚠️ Renamed config.yaml to config.yml

Added

• Complete API rewrite with improved performance
• WebSocket support for real-time updates

Migration Guide

See MIGRATION_v2.md for upgrade instructions.

Release Notes Format

Release v2.1.0 - "Feature Release Name"

Released: January 15, 2024

🎉 Highlights

This release brings major improvements to authentication and user experience:

• OAuth2 Support: Users can now sign in with Google, GitHub, and Microsoft
• Dark Mode: Toggle between light and dark themes
• Performance: 40% faster API response times

✨ New Features

• OAuth2 authentication with popular providers (#456)
• User profile management API (#478)
• Dark mode toggle in settings (#492)
• Export data in CSV format (#501)

🐛 Bug Fixes

• Fixed memory leak in WebSocket connections (#489)
• Resolved incorrect date formatting in reports (#495)
• Fixed race condition in concurrent API requests (#503)

🔄 Changes

• Improved error messages across the application
• Updated all dependencies to latest stable versions
• Refined UI animations for smoother experience

🔒 Security

• Patched XSS vulnerability in user input validation
• Updated JWT library to address CVE-2024-1234

📚 Documentation

• Added OAuth2 setup guide
• Updated API reference with new endpoints
• Improved troubleshooting section

🙏 Contributors

Thank you to all contributors who made this release possible:

• @alice - OAuth2 implementation
• @bob - Dark mode feature
• @charlie - Bug fixes and testing

📦 Installation

npm install project-name@2.1.0
# or
yarn add project-name@2.1.0

🔗 Links Full Changelog Documentation Migration Guide

Note: This is a minor release. No breaking changes. Safe to upgrade from 2.0.x.

Semantic Versioning Rules

Given a version number MAJOR.MINOR.PATCH (e.g., 2.1.0):

1. MAJOR (2.x.x → 3.x.x)
2. Breaking changes
3. Incompatible API changes

4. Removed features

5. MINOR (2.1.x → 2.2.x)

6. New features
7. Backward-compatible functionality

8. Deprecated features

9. PATCH (2.1.0 → 2.1.1)

10. Bug fixes
11. Security patches
12. Performance improvements

Special versions: - 0.x.x - Initial development (breaking changes allowed in minor) - x.y.0-alpha.1 - Pre-release - x.y.0-beta.2 - Beta release - x.y.0-rc.1 - Release candidate

Git Commands for Changelog Generation

# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Get commits between two tags
git log v2.0.0..v2.1.0 --oneline

# Get commits with PR numbers
git log --merges --pretty=format:"%s" v2.0.0..HEAD

# Get contributors
git log v2.0.0..HEAD --format='%aN' | sort -u

# Get commit count by type
git log v2.0.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs)' | cut -d' ' -f2 | sort | uniq -c

Breaking Changes Detection

Look for these indicators:

Commit message contains BREAKING CHANGE:
Commit type has ! (e.g., feat!:)
PR labeled with "breaking-change"
Major dependency updates
API endpoint changes
Config file format changes

Document clearly:

### Breaking Changes

⚠️ **API Response Format Changed**

The `/api/users` endpoint now returns:

```json
// Before
{ "data": [...] }

// After
{ "users": [...], "total": 100 }

Migration: Update your API client to access users instead of data.

Automation Tools

Using conventional-changelog

```bash npm install -g conventional-changelog-cli

Generate changelog

conventional-changelog -p angular -i CHANGELOG.md -s

Generate for specific version

conventional-changelog -p angular -i CHANGELOG.md -s -r 0

Using git-cliff

Install git-cliff

cargo install git-cliff

Generate changelog

git-cliff --tag v2.1.0 > CHANGELOG.md

Generate release notes

git-cliff --tag v2.1.0 --unreleased

GitHub Release Script

!/bin/bash

scripts/release.sh

VERSION=$1 PREVIOUS_TAG=$(git describe --tags --abbrev=0)

Generate release notes

gh release create "$VERSION" \ --title "Release $VERSION" \ --notes "$(git log $PREVIOUS_TAG..HEAD --pretty=format:'- %s')"

User-Facing vs Developer-Facing User-Facing (Release Notes) Focus on benefits and features Less technical jargon Include screenshots/demos Highlight user experience improvements Provide upgrade instructions Developer-Facing (Changelog) Technical details API changes Breaking changes with migration guides Dependencies updates Internal refactorings Templates by Project Type Library/Package

Focus on: API changes, breaking changes, new methods

Application

Focus on: New features, bug fixes, UI improvements

CLI Tool

Focus on: New commands, flag changes, behavior changes

API Service

Focus on: Endpoint changes, performance, security

Best Practices Be specific: "Fixed login bug" → "Fixed session timeout on mobile" Link issues: Reference GitHub issues (#123) Credit contributors: Acknowledge work Highlight impact: Mark breaking changes clearly Group logically: By type, not chronologically Update regularly: With each release Follow conventions: Keep a Changelog format Semantic versioning: Use correctly Changelog Entry Examples Good Examples

Added

• OAuth2 authentication support (#456) - @alice
• Export data in CSV format with custom column selection (#501)

Fixed

• Resolved memory leak in WebSocket connections affecting long-running sessions (#489)
• Fixed race condition in concurrent API requests that caused data inconsistency (#503)

Bad Examples

Added

• Added stuff
• New feature

Fixed

• Fixed bug
• Updates

Version Suggestion Algorithm If breaking changes detected: MAJOR++, MINOR=0, PATCH=0 Else if new features: MINOR++, PATCH=0 Else if only fixes: PATCH++

Release Checklist

Before publishing release:

Review all commits since last release Identify breaking changes Categorize changes properly Update CHANGELOG.md Write release notes Update version in package.json/pyproject.toml Create git tag Push tag to trigger CI/CD Publish to package registry (npm, PyPI, etc.) Create GitHub release with notes Announce on relevant channels Output Checklist

Every changelog generation should provide:

Formatted CHANGELOG.md following Keep a Changelog Release notes draft (user-friendly) Semantic version suggestion (X.Y.Z) Breaking changes clearly marked Migration guide for breaking changes Git tag command to run Links to compare view