Release Artifact Generation

Generate release artifacts from git history between two refs. Artifacts include categorized changelogs and statistics.

Overview

The smooth release generate command analyzes commits and pull requests between two git refs (tags, branches, or commits) and generates structured release documentation:

Categorized changes: Features, fixes, documentation, improvements
Breaking change detection: Identified from commit messages and PR labels
Contributor statistics: Commit counts and contributor list
GitHub Releases integration: Direct publishing with --push flag

How It Works

Tag releases with semantic versioning (e.g., v1.0.0, v1.1.0)
Run smooth release generate
The system fetches commits between refs via git/GitHub API
Commits are categorized by type (feat, fix, docs, etc.)
Artifact is output to stdout or published to GitHub Releases

The system analyzes:

All commits between refs
Pull requests merged in the range
Commit message types and scopes
Breaking change indicators (BREAKING CHANGE: in body, ! after type)
Contributors and commit 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:

```bash
# 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:

{
  "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

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

```bash
# 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 artifact generation:

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

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

See Configuration for additional options.

Security and Data Handling

Smoothdev encrypts customer data in transit and at rest using tenant-scoped encryption keys. Source data is processed only for the requested operation and is not retained long term. Generated artifacts are returned to the user. Operational metrics and validation logs are retained to improve system reliability and quality.

Limitations

Requires valid GitHub token with repo scope for private repositories
Maximum of 500 commits between refs for analysis
Tag auto-detection requires at least two semantic version tags in repository
The --push flag requires repo scope on the GitHub token
Breaking change detection relies on conventional commit format (BREAKING CHANGE: or ! suffix)
Contributor statistics require GitHub API access; local-only repositories show commit counts only
Custom changelog formats are not supported; output follows standard markdown structure

Release Artifact 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

Breaking Changes

Examples

Minor Release (New Features)

Patch Release (Bug Fixes)

Major Release (Breaking Changes)

🎉 New Features

📊 Statistics

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

Security and Data Handling

Limitations

See Also