Pull Request Generation

Generate professional PR titles and comprehensive summaries automatically from GitHub PR data.

Overview

The SmoothDev CLI fetches your pull request data from GitHub and uses AI to generate:

Concise titles (max 250 characters) following conventional commit format
Structured summaries with overview, changes, testing, and documentation sections
Clean markdown ready to paste into GitHub

The AI analyzes commits, file changes, and PR metadata to create documentation that clearly communicates what changed and why.

How It Works

Create a PR on GitHub (or have an existing one)
Run the generator with smooth pr generate --pr-number <number>
Review the output - title and summary are generated
Update GitHub - manually copy/paste or use --push to update automatically

The AI examines:

All commits in the PR
Files changed and their types
PR metadata (labels, assignees, etc.)
Commit messages and patterns
Code diff context

Basic Usage

Generate PR Title and Summary

# Auto-detect owner/repo from git remote
smooth pr generate --pr-number 42

# On branch "pr-42" - auto-detects everything!
smooth pr generate

Example Output:

feat: implement smart defaults and configuration system

# PR Summary

Generated by: *Smoothdev.io*

## Overview

This PR introduces a four-tier configuration precedence system that enables smart defaults
and auto-detection of repository context, significantly reducing the need for repetitive
CLI flags.

## Changes

### Added
- Four-tier configuration precedence (CLI flags → Git context → Repo config → User config)
- Auto-detection of owner/repo from git remotes
- PR number detection from branch names
- Smart tag detection for release notes
- Configuration management commands (`smooth config`)

### Modified
- Updated all commands to support smart defaults
- Enhanced error messages with context information

## Testing

- Added 53 new tests covering auto-detection scenarios
- All existing tests passing
- Coverage maintained at 85%+

## Documentation

- Updated README with smart defaults examples
- Added ADR for configuration system design
- Created user guide for configuration management

Generate Only Title

smooth pr generate --pr-number 42 --title

Output:

feat: implement smart defaults and configuration system

Generate Only Summary

smooth pr generate --pr-number 42 --summary

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 pr generate --pr-number 42  # No need to specify owner/repo!

PR Number from Branch Name

Detected from branch naming patterns:

# Branch: pr-42
# Branch: 42-feature-name
# Branch: feature-pr-42

smooth pr generate  # Auto-detects PR number 42!

Verbose Mode

See where values come from:

smooth pr generate --pr-number 42 --verbose

Output:

📋 Context Resolution:
  owner: smoothdev-io (from git remote)
  repo: my-repo (from git remote)
  pr_number: 42 (from CLI flag)
  output: text (from user config)

Fetching PR data from GitHub...
Generating PR title...
Generating PR summary...

Advanced Usage

Push to GitHub

Automatically update the PR on GitHub:

smooth pr generate --pr-number 42 --push

Requirements:

GitHub token set (see Installation Guide)
Write permissions on the repository

JSON Output

Get structured output for scripting:

smooth pr generate --pr-number 42 --output json

Output:

{
  "title": "feat: implement smart defaults and configuration system",
  "summary": "# PR Summary\n\nGenerated by: *Smoothdev.io*\n\n## Overview\n\n..."
}

Fast Mode (Skip Quality Judging)

For faster generation with slightly lower quality:

smooth pr generate --pr-number 42 --skip-judging

This skips the quality judging step, reducing generation time by ~50% but potentially producing less polished output. Useful for:

Very large PRs (100+ files)
Draft PRs
Quick previews

Explicit Owner/Repo

Override auto-detection:

smooth pr generate --owner my-org --repo my-repo --pr-number 42

PR Title Format

Generated titles follow the Conventional Commits specification:

<type>(<scope>): <description>

Types

Type	Description	Example
`feat`	New feature	`feat: add user authentication`
`fix`	Bug fix	`fix: resolve memory leak`
`docs`	Documentation	`docs: update API reference`
`refactor`	Code refactoring	`refactor: extract validation logic`
`perf`	Performance	`perf: optimize queries`
`test`	Tests	`test: add integration tests`
`build`	Build system	`build: update webpack config`
`ci`	CI/CD	`ci: add GitHub Actions`
`chore`	Maintenance	`chore: update dependencies`

Scope (Optional)

The scope is automatically detected from:

Primary directory changed (e.g., api, cli, docs)
Component name (e.g., auth, config)
Feature area (e.g., database, frontend)

Breaking Changes

Breaking changes are indicated with !:

feat!: change API response format

BREAKING CHANGE: API responses now include metadata wrapper

PR Summary Structure

Generated summaries follow a consistent structure:

Overview

High-level description of what the PR accomplishes and why.

Changes

Categorized list of changes:

Added - New features, files, or functionality
Modified - Changes to existing code
Removed - Deleted code or features
Fixed - Bug fixes
Deprecated - Features marked for removal

Testing

Testing information:

New tests added
Test coverage changes
Manual testing performed
Edge cases covered

Documentation

Documentation updates:

README changes
API documentation
Code comments
ADRs (Architecture Decision Records)

Breaking Changes (if applicable)

Detailed description of breaking changes and migration steps.

Additional Sections (as needed)

Performance Impact
Security Considerations
Dependencies
Deployment Notes

Examples

Feature PR

PR #123: Add User Authentication

Generated Title:

feat(auth): add Auth0 authentication with device flow

Generated Summary:

# PR Summary

Generated by: *Smoothdev.io*

## Overview

This PR implements user authentication using Auth0's device flow, enabling secure
authentication without requiring a browser redirect. Users authenticate via a device
code displayed in the terminal.

## Changes

### Added
- Auth0 device flow authentication
- Token storage with secure file permissions (0600)
- Auth command group (login, logout, apikey-set, apikey-show)
- Automatic token refresh logic
- Authentication mode selection (jwt, api-key, auto)

### Modified
- Updated API client to include authentication headers
- Enhanced error messages for authentication failures

## Testing

- Added 15 unit tests for authentication flow
- Added integration tests for token refresh
- Manual testing on macOS and Linux
- Verified secure file permissions on token storage

## Documentation

- Updated README with authentication section
- Added authentication guide to docs
- Created ADR for Auth0 integration decision

Bug Fix PR

PR #456: Fix Memory Leak in Cache

Generated Title:

fix(cache): prevent memory leak in LRU cache implementation

Generated Summary:

# PR Summary

Generated by: *Smoothdev.io*

## Overview

Fixes a memory leak in the LRU cache implementation where evicted items were not
properly garbage collected due to circular references.

## Changes

### Fixed
- Break circular references in cache nodes on eviction
- Properly clean up weak references
- Add explicit cleanup in cache.clear()

### Added
- Memory profiling test to detect leaks
- Stress test with 10k cache operations

## Testing

- Added memory leak detection test
- Verified fix with memory profiler
- All existing cache tests passing
- Stress tested with large datasets

## Performance Impact

- No performance degradation
- Memory usage reduced by ~30% under load

Documentation PR

PR #789: Update API Documentation

Generated Title:

docs(api): add examples and improve error documentation

Generated Summary:

# PR Summary

Generated by: *Smoothdev.io*

## Overview

Improves API documentation with practical examples, better error descriptions,
and updated endpoint specifications.

## Changes

### Added
- Code examples for each endpoint
- Error response documentation
- Rate limiting information
- Authentication examples

### Modified
- Updated OpenAPI specification
- Improved parameter descriptions
- Fixed broken links

## Documentation

- Added 20+ code examples
- Updated API reference
- Added troubleshooting section

Best Practices

Before Generating

Create a clear PR - Write a descriptive PR description on GitHub
Use meaningful commits - Good commit messages lead to better PR summaries
Label your PR - Labels help categorize the PR type
Link issues - Reference related issues in commits or PR description

After Generating

Review the output - Ensure accuracy and completeness
Add context - Include any missing information the AI couldn't infer
Check formatting - Verify markdown renders correctly
Update GitHub - Copy to GitHub or use --push

Tips for Better PR Documentation

Atomic PRs - One feature or fix per PR
Clear commits - Well-written commits improve PR summaries
Test coverage - Include testing information in commits
Breaking changes - Clearly mark breaking changes in commits

Troubleshooting

"Error fetching PR data"

Problem: Can't fetch PR from GitHub API.

Solutions:

Verify PR number is correct
Check GitHub token is set and valid
Ensure you have read access to the repository
Check GitHub API rate limits

# Verify token
echo $GITHUB_TOKEN

# Check rate limit
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

"Could not determine owner/repo"

Problem: Auto-detection failed.

Solutions:

Ensure you're in a git repository
Check git remote is configured

# Check git remote
git remote -v

# Add remote if missing
git remote add origin git@github.com:owner/repo.git

# Or specify explicitly
smooth pr generate --owner my-org --repo my-repo --pr-number 42

"Could not detect PR number"

Problem: Branch name doesn't match expected patterns.

Solutions:

Specify PR number explicitly: --pr-number 42
Rename branch to include PR number: git branch -m pr-42
Use pattern: pr-<number>, <number>-description, or description-pr-<number>

Generated summary is incomplete

Problem: Summary missing important details.

Solutions:

Ensure PR has meaningful commits
Add more context in commit messages
Use --latency-profile quality (if available)
Edit the generated summary to add missing details

Integration with GitHub Actions

Automatic PR Documentation

Generate PR documentation automatically when PRs are created:

.github/workflows/pr-documentation.yml:

name: Generate PR Documentation

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

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

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

      - name: Generate PR Documentation
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SMOOTHDEV_API_KEY: ${{ secrets.SMOOTHDEV_API_KEY }}
        run: |
          smooth pr generate \
            --pr-number ${{ github.event.pull_request.number }} \
            --push

Configuration

Configure PR 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.

Pull Request Generation

Overview

How It Works

Basic Usage

Generate PR Title and Summary

Generate Only Title

Generate Only Summary

Smart Auto-Detection

Owner and Repository

PR Number from Branch Name

Verbose Mode

Advanced Usage

Push to GitHub

JSON Output

Fast Mode (Skip Quality Judging)

Explicit Owner/Repo

PR Title Format

Types

Scope (Optional)

Breaking Changes

PR Summary Structure

Overview

Changes

Testing

Documentation

Breaking Changes (if applicable)

Additional Sections (as needed)

Examples

Feature PR

Bug Fix PR

Documentation PR

Best Practices

Before Generating

After Generating

Tips for Better PR Documentation

Troubleshooting

"Error fetching PR data"

"Could not determine owner/repo"

"Could not detect PR number"

Generated summary is incomplete

Integration with GitHub Actions

Automatic PR Documentation

Configuration

See Also