Release Notes Generation

Generate comprehensive, structured release notes automatically from your git history.

Overview

The SmoothDev CLI analyzes commits and pull requests between two git refs (tags, branches, or commits) and generates professional release notes with:

Categorized changes (features, fixes, documentation, etc.)
Breaking change detection with migration guidance
Contributor statistics and acknowledgments
Semantic versioning support
GitHub Releases integration for automatic publishing

The AI examines commit messages, PR data, and code changes to create clear, organized documentation that serves both technical and business audiences.

How It Works

Tag your releases with semantic versioning (e.g., v1.0.0, v1.1.0)
Run the generator with smooth release generate
Review the output - categorized changelog with statistics
Publish - manually copy/paste or use --push to create GitHub Release

The AI examines:

All commits between refs
Pull requests merged in the range
Commit message types and scopes
Breaking change indicators
Contributors and statistics

Basic Usage

Generate from Latest Tags

# Auto-detects latest two tags
smooth release generate

This automatically finds the most recent tag and the previous tag, generating release notes for everything in between.

Specify Tags Explicitly

# Generate notes from v1.0.0 to v1.1.0
smooth release generate --from-tag v1.0.0 --to-tag v1.1.0

# Generate from tag to HEAD
smooth release generate --from-tag v1.0.0 --to-tag HEAD

Example Output:

# Release v1.1.0

## 🎉 New Features

- **Smart Defaults**: Four-tier configuration precedence system
- **Auto-Detection**: Automatic owner/repo detection from git remotes
- **PR Number Detection**: Extract PR numbers from branch names
- **Config Management**: New `smooth config` command group

## 🐛 Bug Fixes

- Fixed issue with large diff handling in commit generation
- Resolved GitHub API rate limiting edge cases
- Corrected token refresh logic in authentication

## 📚 Documentation

- Added comprehensive configuration guide
- Updated README with smart defaults examples
- Created ADR for configuration system
- Improved API reference documentation

## 🔧 Improvements

- Reduced required CLI flags by 80%
- Enhanced error messages with context
- Improved verbose mode output
- Optimized API response caching

## 📊 Statistics

- **Commits**: 47
- **Contributors**: 3
- **Files Changed**: 28
- **Additions**: 1,234
- **Deletions**: 567

Smart Auto-Detection

The CLI automatically detects context from your git repository:

Owner and Repository

Detected from git remote URLs:

# Git remote: git@github.com:smoothdev-io/my-repo.git
# Auto-detects: owner=smoothdev-io, repo=my-repo

smooth release generate  # No need to specify owner/repo!

Latest Tags

Automatically finds the two most recent tags:

# Tags: v1.0.0, v1.1.0, v1.2.0
# Auto-detects: from=v1.1.0, to=v1.2.0

smooth release generate  # Generates notes for v1.2.0!

Verbose Mode

See where values come from:

smooth release generate --verbose

Output:

📋 Context Resolution:
  owner: smoothdev-io (from git remote)
  repo: my-repo (from git remote)
  from_tag: v1.0.0 (auto-detected)
  to_tag: v1.1.0 (auto-detected)
  output: text (from user config)

Fetching release data from GitHub...
Generating release notes...

Advanced Usage

Push to GitHub Releases

Automatically create or update a GitHub Release:

smooth release generate \
  --from-tag v1.0.0 \
  --to-tag v1.1.0 \
  --push \
  --tag v1.1.0

Requirements:

GitHub token set (see Installation Guide)
Write permissions on the repository
Tag must exist in the repository

Create Draft Release

Create a draft release for review before publishing:

smooth release generate \
  --push \
  --tag v1.1.0 \
  --draft

Draft releases are visible only to repository collaborators and can be edited before publishing.

Mark as Prerelease

For alpha, beta, or RC releases:

smooth release generate \
  --push \
  --tag v1.1.0-beta.1 \
  --prerelease

Prereleases are marked as "not ready for production" on GitHub.

Custom Release Name

Override the default release name:

smooth release generate \
  --push \
  --tag v1.1.0 \
  --name "Version 1.1.0 - Smart Defaults"

JSON Output

Get structured output for scripting:

smooth release generate --output json

Output:

{
  "version": "v1.1.0",
  "date": "2025-11-15",
  "features": [
    "Smart Defaults: Four-tier configuration precedence system",
    "Auto-Detection: Automatic owner/repo detection"
  ],
  "fixes": [
    "Fixed issue with large diff handling"
  ],
  "statistics": {
    "commits": 47,
    "contributors": 3,
    "files_changed": 28
  }
}

Fast Mode (Skip Quality Judging)

For very large releases (100+ commits):

smooth release generate --skip-judging

This reduces generation time by ~50% but may produce less polished output.

Release Notes Structure

Generated release notes follow a consistent structure:

Version Header

# Release v1.1.0

New Features (🎉)

New functionality added in this release:

## 🎉 New Features

- **Feature Name**: Brief description
- **Another Feature**: What it does

Bug Fixes (🐛)

Issues resolved in this release:

## 🐛 Bug Fixes

- Fixed issue with X
- Resolved problem where Y
- Corrected Z behavior

Documentation (📚)

Documentation updates:

## 📚 Documentation

- Added guide for X
- Updated API reference
- Improved examples

Improvements (🔧)

Enhancements and optimizations:

## 🔧 Improvements

- Improved performance of X
- Enhanced error messages
- Optimized Y algorithm

Breaking Changes (⚠️)

Changes that break backward compatibility:

## ⚠️ Breaking Changes

- **API Response Format**: Changed from X to Y

  **Migration**: Update your code to handle new format:
  ```python
  # Before
  data = response['data']

  # After
  data = response['result']['data']
  ```

Deprecations (🗑️)

Features marked for removal:

## 🗑️ Deprecations

- `old_function()` is deprecated, use `new_function()` instead
- Will be removed in v2.0.0

Statistics (📊)

Contribution and change metrics:

## 📊 Statistics

- **Commits**: 47
- **Contributors**: 3
- **Files Changed**: 28
- **Additions**: 1,234
- **Deletions**: 567

Contributors (👥)

Acknowledgment of contributors:

## 👥 Contributors

Thanks to all contributors who made this release possible:

- @alice (23 commits)
- @bob (15 commits)
- @charlie (9 commits)

Semantic Versioning

Release notes support semantic versioning (semver):

Version Format

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples:

1.0.0 - Major release
1.1.0 - Minor release (new features)
1.1.1 - Patch release (bug fixes)
1.2.0-beta.1 - Prerelease
1.2.0+20250115 - Build metadata

Version Detection

The CLI automatically detects version from tags:

# Tag: v1.1.0
# Detected version: 1.1.0

# Tag: 1.1.0
# Detected version: 1.1.0

# Tag: release-1.1.0
# Detected version: 1.1.0

Breaking Changes

Breaking changes are detected from:

Commit messages with BREAKING CHANGE: footer
Commit type with ! (e.g., feat!:, fix!:)
Major version bumps (1.x.x → 2.0.0)

Examples

Minor Release (New Features)

Command:

smooth release generate --from-tag v1.0.0 --to-tag v1.1.0

Output:

# Release v1.1.0

## 🎉 New Features

- **Smart Configuration**: Four-tier precedence system for configuration
- **Auto-Detection**: Automatic detection of owner/repo from git remotes
- **PR Auto-Detection**: Extract PR numbers from branch names
- **Config Commands**: New command group for configuration management

## 🐛 Bug Fixes

- Fixed authentication token refresh logic
- Resolved issue with large git diffs
- Corrected error handling in API client

## 📚 Documentation

- Added configuration guide
- Updated README with examples
- Created ADR for smart defaults

## 📊 Statistics

- **Commits**: 47
- **Contributors**: 3
- **Files Changed**: 28

Patch Release (Bug Fixes)

Command:

smooth release generate --from-tag v1.1.0 --to-tag v1.1.1

Output:

# Release v1.1.1

## 🐛 Bug Fixes

- Fixed memory leak in cache implementation
- Resolved race condition in token refresh
- Corrected validation logic for config values

## 🔧 Improvements

- Improved error messages for authentication failures
- Enhanced logging in verbose mode

## 📊 Statistics

- **Commits**: 8
- **Contributors**: 2
- **Files Changed**: 5

Major Release (Breaking Changes)

Command:

smooth release generate --from-tag v1.9.0 --to-tag v2.0.0

Output:

# Release v2.0.0

## ⚠️ Breaking Changes

- **API Response Format**: Changed response structure to include metadata

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

  **After:**
  ```json
  {
    "data": [...],
    "metadata": {
      "page": 1,
      "total": 100
    }
  }
  ```

  **Migration**: Update API clients to access `response.data` instead of `response`.

- **Configuration File**: Renamed `.smoothdev.json` to `.smoothdev.config.json`

  **Migration**: Rename your config file:
  ```bash
  mv .smoothdev.json .smoothdev.config.json
  ```

## 🎉 New Features

- **Pagination Support**: Added pagination to all list endpoints
- **Metadata API**: New endpoint for resource metadata

## 📊 Statistics

- **Commits**: 156
- **Contributors**: 8
- **Files Changed**: 89

Best Practices

Tagging Strategy

Use semantic versioning - Follow semver conventions
Tag consistently - Use same format (e.g., always v1.0.0)
Tag releases - Create tags for all releases
Annotated tags - Use git tag -a for better metadata

# Create annotated tag
git tag -a v1.1.0 -m "Release v1.1.0"

# Push tag to remote
git push origin v1.1.0

Commit Messages

Good commit messages lead to better release notes:

Use conventional commits - feat:, fix:, docs:, etc.
Be descriptive - Clear, concise descriptions
Include context - Explain why, not just what
Mark breaking changes - Use BREAKING CHANGE: footer

Release Workflow

Finish development - Complete all features/fixes
Update version - Bump version in package files
Generate notes - Run smooth release generate
Review output - Verify accuracy and completeness
Create tag - Tag the release commit
Push to GitHub - Use --push or manually create release

Troubleshooting

"Could not determine tags"

Problem: No tags found in repository.

Solutions:

Create tags for your releases:

git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0

Specify tags explicitly:

smooth release generate --from-tag main --to-tag develop

"No commits found between refs"

Problem: No commits exist between the specified refs.

Solutions:

Verify refs exist:

git log v1.0.0..v1.1.0

Check tag order (from should be older than to)
Ensure tags are pushed to remote

Generated notes are empty

Problem: No categorized changes in output.

Solutions:

Use conventional commit format in commit messages
Ensure commits have clear types (feat:, fix:, etc.)
Check that commits exist between refs

"GitHub API rate limit exceeded"

Problem: Too many API requests.

Solutions:

Wait for rate limit reset (shown in error message)
Use authenticated requests (set GITHUB_TOKEN)
Reduce frequency of generation

Integration with CI/CD

Automatic Release Notes

Generate release notes automatically when tags are pushed:

.github/workflows/release.yml:

name: Generate Release Notes

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Fetch all history for tags

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'

      - name: Install SmoothDev CLI
        run: pip install smooth-cli

      - name: Generate and Publish Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SMOOTHDEV_API_KEY: ${{ secrets.SMOOTHDEV_API_KEY }}
        run: |
          # Extract version from tag
          VERSION=${GITHUB_REF#refs/tags/}

          # Generate and push release notes
          smooth release generate \
            --to-tag $VERSION \
            --push \
            --tag $VERSION

Configuration

Configure release generation behavior:

# Set default output format
smooth config set defaults.output json

# Set default owner
smooth config set defaults.owner my-org

See the Configuration Guide for more options.

Release Notes Generation

Overview

How It Works

Basic Usage

Generate from Latest Tags

Specify Tags Explicitly

Smart Auto-Detection

Owner and Repository

Latest Tags

Verbose Mode

Advanced Usage

Push to GitHub Releases

Create Draft Release

Mark as Prerelease

Custom Release Name

JSON Output

Fast Mode (Skip Quality Judging)

Release Notes Structure

Version Header

New Features (🎉)

Bug Fixes (🐛)

Documentation (📚)

Improvements (🔧)

Breaking Changes (⚠️)

Deprecations (🗑️)

Statistics (📊)

Contributors (👥)

Semantic Versioning

Version Format

Version Detection

Breaking Changes

Examples

Minor Release (New Features)

Patch Release (Bug Fixes)

Major Release (Breaking Changes)

Best Practices

Tagging Strategy

Commit Messages

Release Workflow

Troubleshooting

"Could not determine tags"

"No commits found between refs"

Generated notes are empty

"GitHub API rate limit exceeded"

Integration with CI/CD

Automatic Release Notes

Configuration

See Also