release-pilot

Automated release management CLI — semantic versioning, changelog generation, and GitHub releases from conventional commits.

---

Why release-pilot?

Release management is tedious. Version bumps, changelogs, git tags — it's manual, error-prone busywork. release-pilot automates the entire process using Conventional Commits:

• Auto Version Bumps — Determines major/minor/patch from commit types
• Changelog Generation — Creates formatted CHANGELOG.md from git history
• Pre-release Checks — Validates clean tree, branch, remote, and commits
• Multi-file Version Updates — Syncs version across pyproject.toml, package.json, init.py, Cargo.toml, etc.
• Git Tag Creation — Creates annotated tags with release messages
• Dry Run Mode — Preview everything before committing to changes
• Commit Analytics — Visualize commit breakdown by type

---

Installation

pip install release-pilot-cli

---

Quick Start

# View what the next release would look like
release-pilot check

# Preview changelog from conventional commits
release-pilot changelog

# Create a release (dry run)
release-pilot release --dry-run

# Create a release for real
release-pilot release --yes

# Create and push release
release-pilot release --push --yes

---

Commands

release — Create a New Release

The main command. Analyzes commits, bumps version, generates changelog, creates tag.

release-pilot release                    # Auto-detect bump, confirm
release-pilot release --bump minor       # Force minor bump
release-pilot release --dry-run          # Preview only
release-pilot release --push --yes       # Release + push, no prompt
release-pilot release --branch main      # Require main branch
release-pilot release --no-changelog     # Skip changelog update
release-pilot release --no-version-update # Skip version file changes

Option	Description
-b, --bump	Force bump type: major, minor, or patch
-p, --push	Push tag and commits to remote after release
-n, --dry-run	Preview without making any changes
-y, --yes	Skip confirmation prompt
--branch	Require specific branch (e.g., main)
--no-changelog	Skip CHANGELOG.md generation
--no-version-update	Skip version file updates

check — Pre-release Validation

Run all checks without making changes:

release-pilot check
release-pilot check --branch main

Checks performed:

• Git repository detection
• Clean working tree (no uncommitted changes)
• Branch validation (optional: require specific branch)
• Remote origin configured
• New commits exist since last tag
• Conventional commits found

log — View Commit Summary

release-pilot log                  # Summary since last tag
release-pilot log --since v1.0.0   # Since specific tag
release-pilot log --show-all       # Show individual commits

changelog — Generate Changelog

release-pilot changelog                        # Preview in terminal
release-pilot changelog --output CHANGELOG.md  # Write to file
release-pilot changelog --bump minor           # Force version in header

version — Show Current Version

release-pilot version    # Shows git tag version + version files

Detects version in: pyproject.toml, package.json, __init__.py, setup.py, setup.cfg, Cargo.toml, VERSION, version.py

history — Release History

release-pilot history    # List all releases from git tags

bump — Manual Version Update

Set version across all project files without creating a release:

release-pilot bump 2.0.0
release-pilot bump 1.5.0 --dry-run

init — Commit Format Guide

release-pilot init    # Show conventional commit format reference

---

Conventional Commits

release-pilot uses Conventional Commits to determine version bumps automatically:

Commit	Bump	Example
feat:	Minor	feat: add search functionality
feat!:	Major	feat!: redesign API
fix:	Patch	fix: handle null input
perf:	Patch	perf: optimize query speed
docs:	Patch	docs: update README
refactor:	Patch	refactor: simplify auth flow
test:	Patch	test: add unit tests
chore:	Patch	chore: update dependencies
ci:	Patch	ci: add GitHub Actions workflow
build:	Patch	build: upgrade webpack

Scopes

Optional scope in parentheses:

feat(auth): add OAuth2 login
fix(parser): handle unicode
docs(api): add endpoint docs

Breaking Changes

Two ways to mark breaking changes (triggers major bump):

feat!: remove deprecated endpoints

# or with footer
feat: new config format

BREAKING CHANGE: old config format removed

---

Version Detection

release-pilot automatically finds and updates version strings in:

File	Pattern
pyproject.toml	version = "X.Y.Z"
package.json	"version": "X.Y.Z"
__init__.py	__version__ = "X.Y.Z"
setup.py	version="X.Y.Z"
setup.cfg	version = X.Y.Z
Cargo.toml	version = "X.Y.Z"
VERSION	X.Y.Z
version.py	__version__ = "X.Y.Z" or VERSION = "X.Y.Z"

---

Workflow Example

# 1. Write code with conventional commits
git commit -m "feat(auth): add JWT support"
git commit -m "fix(db): connection pool leak"
git commit -m "docs: update API reference"

# 2. Check what the release looks like
release-pilot check

# 3. Preview the changelog
release-pilot changelog

# 4. Create the release
release-pilot release --yes --push

What happens:

1. Commits analyzed → feat found → minor bump
2. Version: 1.0.0 → 1.1.0
3. CHANGELOG.md updated with grouped entries
4. Version files updated (pyproject.toml, __init__.py, etc.)
5. Changes committed: chore(release): 1.1.0
6. Git tag created: v1.1.0
7. Pushed to remote

---

Generated Changelog Format

## [1.1.0] - 2025-01-20

### Features

- **auth:** add JWT support (abc123d)
- add search functionality (def456g)

### Bug Fixes

- **db:** connection pool leak (ghi789j)

### Documentation

- update API reference (jkl012m)

---

Development

git clone https://github.com/SanjaySundarMurthy/release-pilot.git
cd release-pilot
pip install -e ".[dev]"
pytest tests/ -v

---

Author

Sanjay Sundar Murthy

• GitHub: @SanjaySundarMurthy
• Email: sanjaysundarmurthy@gmail.com

---

License

MIT License — see LICENSE for details.