ReleaseCraft

A powerful CLI tool for automating releases, changelogs, and version management with AI-powered release notes generation.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Commands
  • releaser init
  • releaser bump
  • releaser commit-gen
  • releaser commit-lint
  • releaser cache
• Configuration
  • Project Settings
  • Release Configuration
  • Pre-Release Management
  • Changelog Settings
  • AI-Powered Release Notes
  • LLM Configuration
  • Hooks
  • Commit Linting
  • Commit Generation
• Examples
• Advanced Features
  • AI-Generated Release Notes
  • Pre-Release Workflows
  • Custom Prompts
• Contributing
• License

Overview

ReleaseCraft automates your release workflow with intelligent version bumping, changelog generation, and AI-powered release notes. It supports uv, Poetry, npm, and setuptools projects with conventional commits.

Features

✨ Intelligent Version Bumping

• Automatic semantic versioning based on conventional commits
• Support for major, minor, patch, and pre-release versions
• Multiple project types: uv, Poetry, npm, setuptools

🤖 AI-Powered Release Notes

• Generate comprehensive release notes using OpenAI
• Automatic categorization of changes
• Include code diffs for important features
• Customizable prompts

📝 Changelog Management

• Automatic CHANGELOG.md updates
• Conventional commit parsing
• Custom changelog formatting

🔍 Commit Message Tools

• AI-powered commit message generation
• Conventional commit linting
• Interactive commit creation

🎯 Pre-Release Support

• Branch-based pre-release workflows
• Automatic pre-release versioning
• Channel-based releases (alpha, beta, rc)

⚙️ Flexible Configuration

• TOML-based configuration
• Per-project or global settings
• Extensive customization options

Installation

Using pip

pip install releasecraft

From source

git clone https://github.com/yourusername/releasecraft.git
cd releasecraft
pip install -e .

Quick Start

1. Initialize configuration in your project:

cd your-project
releaser init

2. Make some commits following conventional commits:

git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"

3. Bump version and create release:

releaser bump

That's it! ReleaseCraft will automatically:

• Determine the version bump based on commits
• Update version in project files
• Generate changelog
• Create git tag
• Optionally generate AI-powered release notes

Commands

releaser init

Initialize ReleaseCraft configuration for your project.

# Interactive setup
releaser init

# Non-interactive with defaults
releaser init --yes

# Global configuration
releaser init --global

# Specify project type
releaser init --project-type poetry

Options:

• --yes: Accept all defaults, non-interactive
• --global: Write to ~/.releaser/config.toml
• --path PATH: Custom config file path
• --project-type {auto,uv,poetry,setuptools,npm,cargo}: Specify project type
• --tag-prefix PREFIX: Default tag prefix (default: "v")
• --use-native/--no-use-native: Use native tooling when available

releaser bump

Bump version and create release (interactive by default).

# Auto-detect version bump from commits
releaser bump

# Force specific version bump
releaser bump --type major
releaser bump --type minor
releaser bump --type patch

# Set exact version
releaser bump --manual 2.0.0

# Create pre-release
releaser bump --pre

# Finalize pre-release to stable
releaser bump --finalize

# Dry-run mode (preview only)
releaser bump --dry-run

# With custom release notes
releaser bump --notes "Release notes here"
releaser bump --notes-file notes.txt

# Update changelog
releaser bump --changelog

# Push to remote after release
releaser bump --push

Interactive behavior (no --type/--manual):

• On a stable version (e.g. 1.0.0), releaser bump shows a menu: Patch → 1.0.1, Minor → 1.1.0, Major → 2.0.0, Manual, Cancel.
• On a stable version, releaser bump --pre shows: Patch → 1.0.1-rc.1, Minor → 1.1.0-rc.1, Major → 2.0.0-rc.1, Manual, Cancel.
• On a pre-release (e.g. 1.0.0-rc.1), releaser bump --pre shows: Continue pre-release → 1.0.0-rc.2, Patch base → 1.0.1-rc.1, Minor base → 1.1.0-rc.1, Major base → 2.0.0-rc.1, Finalize to stable → 1.0.0, Manual, Cancel.

Options (flags):

• --manual VERSION: Set exact version
• --type {major,minor,patch}: Force bump type
• --pre: Create pre-release version
• --finalize: Convert pre-release to stable
• --dry-run: Preview changes without applying
• --push: Push to remote after creating release
• --no-commit: Don't create commit
• --no-tag: Don't create tag
• --notes TEXT: Inline release notes
• --notes-file PATH: Read release notes from file
• --changelog: Append to CHANGELOG.md
• --changelog-file PATH: Custom changelog path
• --version-source {file,local_tag,remote_tag,auto}: Version source

releaser commit-gen

Generate conventional commit messages from staged changes using AI.

# Generate from staged changes
git add .
releaser commit-gen --staged

# Generate and auto-commit
releaser commit-gen --staged --yes

# Generate from specific files
releaser commit-gen --files src/main.py src/utils.py

# Include ticket reference
releaser commit-gen --staged --ticket JIRA-123

# Save to file instead of committing
releaser commit-gen --staged --output commit.txt

# Disable AI, use heuristics only
releaser commit-gen --staged --no-ai

# Custom AI model
releaser commit-gen --staged --model gpt-4

Options:

• --staged: Use staged changes
• --files FILES: Specific files to analyze
• --yes, -y: Auto-commit without prompting
• --ticket TICKET: Include ticket reference
• --output PATH: Write to file instead of committing
• --no-ai: Use heuristics only, disable AI
• --model MODEL: AI model to use
• --temperature FLOAT: AI temperature (0.0-1.0)
• --max-tokens INT: Max AI response tokens
• --history N: Include last N commits as context

releaser commit-lint

Validate commit messages against Conventional Commits specification.

# Lint commit message from file
releaser commit-lint commit-msg.txt

# Lint last commit
releaser commit-lint .git/COMMIT_EDITMSG

# JSON output
releaser commit-lint commit-msg.txt --format json

Options:

• --format {text,json}: Output format
• --config PATH: Custom config file

releaser cache

Manage AI-generated release notes cache.

# Show cache statistics
releaser cache stats

# Clear all cache
releaser cache clear

# Clear cache older than 30 days
releaser cache clear --older-than 30

# Force clear without confirmation
releaser cache clear --force

Options:

• stats: Show cache statistics
• clear: Clear cache entries
• --older-than DAYS: Clear entries older than N days
• --force: Skip confirmation prompt

Configuration

ReleaseCraft uses TOML configuration files. Configuration can be:

• Project-specific: .releaser.toml or .releaser/config.toml
• Global: ~/.releaser/config.toml

Project Settings

[project]
# Provider type: auto, uv, poetry, setuptools, npm, or cargo
type = "auto"

# Tag prefix for git tags (e.g., v1.2.3)
tag_prefix = "v"

# Use native tooling when available (uv version, poetry version, npm version)
use_native = false

Release Configuration

[release]
# Create git commit after version bump
create_commit = true

# Create git tag after version bump
create_tag = true

# Push to remote after release
push = false

# Additional files to update with version
version_targets = []

# Changelog file path
change_log_file = "CHANGELOG.md"

# Allow releasing with uncommitted changes
allow_dirty = false

Pre-Release Management

[release.pre_release]
# Enable pre-release functionality
enabled = true

# Default pre-release channel (alpha, beta, rc, etc.)
default_channel = "rc"

# Auto-increment pre-release number
auto_increment = true

# Reset pre-release on version bump
reset_on_bump = true

# Branches where pre-releases are allowed
apply = ["develop", "release/*"]

# Branches where pre-releases are blocked
block = ["main", "master", "hotfix/*"]

Changelog Settings

[release.change_log]
# Enable changelog generation
enabled = true

# Changelog file path
file = "CHANGELOG.md"

# Mode: 'auto' (from commits) or 'notes' (user notes only)
mode = "auto"

AI-Powered Release Notes

[release.auto_gen_notes]
# Enable AI-powered release notes
enabled = false

# Include code diffs in release notes
include_diff = true

# Always include diffs for these commit types
always_diff_types = ["feat"]

# Maximum commits to analyze
max_commits = 200

# Mode: 'auto' or custom
mode = "auto"

LLM Configuration

[llm-config]
# Enable LLM features (release notes, commit messages)
enabled = false

# LLM provider (currently only 'openai' supported)
provider = "openai"

# Model to use
model = "gpt-4o-mini"

# Environment variable containing API key
api_key_env = "OPENAI_API_KEY"

# Sampling temperature (0.0-1.0)
temperature = 0.2

# Maximum tokens in response
max_tokens = 2500

# Enable response caching
cache = true

# Auto-accept AI suggestions without prompting
accept_automatically = false

# Fail if AI generation fails (otherwise fall back to basic notes)
fail_on_error = false

# Optional: Custom prompt files
# prompt_release_notes_file = "path/to/custom_release_notes.md.j2"
# system_prompt_file = "path/to/custom_system_prompt.md"

Hooks

[hooks]
# Shell commands to run before version bump
pre_bump = []

# Shell commands to run after version bump
post_bump = []

Example with hooks:

[hooks]
pre_bump = ["make test", "make lint"]
post_bump = ["make build", "make docs"]

Commit Linting

[commit_lint]
# Enable commit message linting
enabled = true

# Allowed commit types
types = [
  "feat",
  "fix",
  "docs",
  "chore",
  "refactor",
  "perf",
  "test",
  "build",
  "ci",
  "revert",
  "style"
]

# Skip linting merge commits
skip_merge_commits = true

# Skip linting revert commits
skip_revert_commits = true

Commit Generation

[commit_gen]
# Number of recent commits to use as context
history_commits = 10

# Demote 'feat' to 'chore' if similar to recent commits
demote_feat_if_similar = true

# Allow scope in commit messages
allow_scope = false

Examples

Basic Workflow

# 1. Initialize project
cd my-project
releaser init --project-type poetry

# 2. Make changes and commit
git add .
releaser commit-gen --staged --yes

# 3. Create release
releaser bump --changelog --push

Pre-Release Workflow

# On develop branch
git checkout develop

# Create pre-release for the next version
releaser bump --pre
# Example output: 1.2.0-rc.1 (base bumped from 1.1.0 to 1.2.0, then -rc.1)

# More changes...
releaser bump --pre
# Output: 1.2.0-rc.2

# Ready to release
git checkout main
git merge develop
releaser bump --finalize
# Output: 1.2.0

Manual Version Control

# Set specific version
releaser bump --manual 2.0.0

# Force major bump
releaser bump --type major

# Preview without changes
releaser bump --dry-run

AI-Powered Release Notes

# Enable in config
# [llm-config]
# enabled = true
# model = "gpt-4o-mini"

# Set API key
export OPENAI_API_KEY="your-api-key"

# Create release with AI notes
releaser bump --changelog

# The AI will generate comprehensive release notes
# categorized by type (Features, Bug Fixes, etc.)

Custom Changelog

# Add custom notes
releaser bump \
  --notes "This release includes major performance improvements" \
  --changelog

# From file
releaser bump --notes-file release-notes.md --changelog

Advanced Features

AI-Generated Release Notes

ReleaseCraft can generate comprehensive release notes using OpenAI:

1. Enable AI in configuration:

[llm-config]
enabled = true
model = "gpt-4o-mini"
api_key_env = "OPENAI_API_KEY"

[release.auto_gen_notes]
enabled = true
include_diff = true
always_diff_types = ["feat"]

2. Set your API key:

export OPENAI_API_KEY="your-openai-api-key"

3. Generate release:

releaser bump --changelog

The AI will:

• Analyze all commits since last release
• Categorize changes (Features, Bug Fixes, etc.)
• Generate human-readable descriptions
• Include code diffs for important changes
• Format output in Markdown

Pre-Release Workflows

Configure branch-based pre-release rules:

[release.pre_release]
enabled = true
default_channel = "rc"

# Pre-releases allowed on these branches
apply = ["develop", "release/*"]

# Pre-releases blocked on these branches
block = ["main", "master", "hotfix/*"]

Usage:

# On develop branch - creates 1.1.0-rc.1
git checkout develop
releaser bump --pre

# Subsequent pre-releases increment: 1.1.0-rc.2, 1.1.0-rc.3, etc.
releaser bump --pre

# On main branch - finalizes to 1.1.0
git checkout main
releaser bump --finalize

Custom Prompts

Customize AI behavior with custom prompts:

1. Create custom prompt file (custom_release_notes.md.j2):

Generate release notes for version {{ version }}.

Commits:
{% for commit in commits %}
- {{ commit.message }}
{% endfor %}

Focus on user-facing changes and improvements.

2. Update configuration:

[llm-config]
prompt_release_notes_file = "custom_release_notes.md.j2"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by the ReleaseCraft team

For more information and updates, visit our GitHub repository.