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](https://keepachangelog.com/en/1.0.0/),

and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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](./docs/MIGRATION_v2.md) for upgrade instructions.

[unreleased]: https://github.com/user/project/compare/v2.1.0...HEAD

[2.1.0]: https://github.com/user/project/compare/v2.0.0...v2.1.0

[2.0.0]: https://github.com/user/project/releases/tag/v2.0.0

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)

   - Breaking changes

   - Incompatible API changes

   - Removed features

2. **MINOR** (2.1.x → 2.2.x)

   - New features

   - Backward-compatible functionality

   - Deprecated features

3. **PATCH** (2.1.0 → 2.1.1)

   - Bug fixes

   - Security patches

   - 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:

// Before

{ "data": [...] }

// After

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

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

Automation Tools

Using conventional-changelog

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