Metadata-Version: 2.4
Name: release-pilot-cli
Version: 1.0.0
Summary: Automated release management CLI — semantic versioning, changelog generation, and GitHub releases from conventional commits
Project-URL: Homepage, https://github.com/SanjaySundarMurthy/release-pilot
Project-URL: Repository, https://github.com/SanjaySundarMurthy/release-pilot
Project-URL: Issues, https://github.com/SanjaySundarMurthy/release-pilot/issues
Author-email: Sanjay Sundar Murthy <sanjaysundarmurthy@gmail.com>
License: MIT
License-File: LICENSE
Keywords: changelog,ci-cd,cli,conventional-commits,devops,git,release,semver,versioning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: toml>=0.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# release-pilot

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

[![PyPI version](https://badge.fury.io/py/release-pilot-cli.svg)](https://pypi.org/project/release-pilot-cli/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## 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](https://www.conventionalcommits.org/):

- **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

```bash
pip install release-pilot-cli
```

---

## Quick Start

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

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

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

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

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

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

```bash
release-pilot history    # List all releases from git tags
```

### `bump` — Manual Version Update

Set version across all project files without creating a release:

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

### `init` — Commit Format Guide

```bash
release-pilot init    # Show conventional commit format reference
```

---

## Conventional Commits

release-pilot uses [Conventional Commits](https://www.conventionalcommits.org/) 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

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

```markdown
## [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

```bash
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](https://github.com/SanjaySundarMurthy)
- Email: sanjaysundarmurthy@gmail.com

---

## License

MIT License — see [LICENSE](LICENSE) for details.
