vership

A release orchestrator that handles version bumping, changelog generation, and publishing — with zero configuration.

$ vership bump patch
✓ No uncommitted changes
✓ On branch main
✓ Tag v0.3.1 does not exist
✓ Lock file in sync
✓ Lint passes
✓ Tests pass
→ Bumping 0.3.0 → 0.3.1
→ Updated rust + maturin
→ Generated changelog (2 entries)
→ Committed: chore: bump version to v0.3.1
→ Tagged: v0.3.1
→ Pushed to origin

Why vership?

Most release tools require config files, plugins, or CI integration before they do anything. vership works out of the box: it detects your project type, runs pre-flight checks, generates a changelog from conventional commits, bumps the version, and pushes — in one command.

Install

# Homebrew
brew install rvben/tap/vership

# From crates.io
cargo install vership

# From PyPI
pip install vership

# From source
git clone https://github.com/rvben/vership && cd vership && cargo install --path .

Quick Start

No setup required. Just use conventional commits and run:

vership bump patch    # 0.1.0 → 0.1.1
vership bump minor    # 0.1.1 → 0.2.0
vership bump major    # 0.2.0 → 1.0.0

Preview before releasing:

vership bump patch --dry-run

Commands

vership bump <patch|minor|major>   Bump version, generate changelog, tag, push
  --dry-run                        Preview without making changes
  --skip-checks                    Skip lint and test checks
  --no-push                        Stop after tagging, do not push
vership changelog                  Preview changelog for unreleased commits
vership preflight                  Run all pre-flight checks
vership status                     Show version, project type, unreleased commits
vership config init                Create vership.toml with defaults
vership schema                     JSON schema for agent integration
vership completions <shell>        Generate shell completions

What It Does

vership bump patch runs this flow:

1. Detect project type (Rust, Rust+Maturin, Node, Go, Python)
2. Check clean working tree, correct branch, tag doesn't exist, lockfile in sync
3. Check lint and tests pass (skippable with --skip-checks)
4. Bump version in project files (Cargo.toml, package.json, pyproject.toml) or tag directly (Go)
5. Generate changelog from conventional commits since last tag
6. Commit, tag, and push

Your existing CI release workflow (GitHub Actions, etc.) triggers on the tag push as usual. vership handles the local side only.

Changelog Format

Generated from conventional commits in Keep a Changelog format:

## [0.2.1](https://github.com/you/repo/compare/v0.2.0...v0.2.1) - 2026-03-28

### Added

- **api**: add user endpoint ([abc1234](https://github.com/you/repo/commit/abc1234))

### Fixed

- correct null handling in parser ([def5678](https://github.com/you/repo/commit/def5678))

Configuration

vership works without any configuration. Only create vership.toml if you need to override defaults:

[project]
branch = "main"              # Branch to release from

[hooks]
pre-bump = "make verify"     # Run before version bump
post-push = "echo done"      # Run after push (e.g. trigger Homebrew update)

[checks]
lint = true                  # Run lint checks (default: true)
tests = true                 # Run tests (default: true)
lint_command = "npm run lint" # Override default lint command
test_command = "npm test"     # Override default test command

[changelog]
unconventional = "exclude"   # "exclude", "include", or "strict"

Agent Integration

vership is designed to work with AI coding assistants:

# Machine-readable project status
vership status --json

# Full command schema for tool discovery
vership schema

License

MIT