# versioneer

> Manage project versions with versioneer. Use this when users want to bump versions (major, minor, patch), sync version files, verify version consistency, or check version status across build systems.

- Author: James Felix Black
- Repository: tftio/claude-skills
- Version: 20260130135044
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/tftio/claude-skills
- Web: https://mule.run/skillshub/@@tftio/claude-skills~versioneer:20260130135044

---

---
name: versioneer
description: Manage project versions with versioneer. Use this when users want to bump versions (major, minor, patch), sync version files, verify version consistency, or check version status across build systems.
tools: Bash, Read, Glob
metadata:
  version: 1.0.0
  tags: [versioning, semver, cli-wrapper]
---

# Versioneer Version Management

This skill provides access to version management through the `versioneer` CLI tool, which synchronizes VERSION files with build system version declarations.

## Tool Location

**Binary:** `$HOME/.local/bin/versioneer`

```bash
# Verify installation
which versioneer
versioneer --version
versioneer doctor
```

## Resource Files

Detailed references are in `resources/`:

- **commands.md**: Full command syntax for show, status, verify, sync, bump, reset
- **workflows.md**: Git integration, release patterns, best practices, CI/CD
- **troubleshooting.md**: Common issues, examples, integration patterns

## What is Versioneer?

Versioneer maintains version consistency across different build systems:
- Keeps a single source of truth in a `VERSION` file
- Synchronizes that version to build system files (Cargo.toml, pyproject.toml, package.json)
- Detects which build systems are present in a project
- Ensures all version declarations stay in sync

## Quick Reference

### Core Commands

```bash
# Show current version
versioneer show

# Check detected build systems
versioneer status

# Verify all versions match
versioneer verify

# Sync VERSION to build systems
versioneer sync

# Check health
versioneer doctor
```

### Version Bumping

```bash
# Patch: bug fixes (1.2.3 -> 1.2.4)
versioneer patch

# Minor: new features (1.2.3 -> 1.3.0)
versioneer minor

# Major: breaking changes (1.2.3 -> 2.0.0)
versioneer major

# Reset to specific version
versioneer reset 2.0.0
```

### Typical Workflow

```bash
# 1. Bump version
versioneer patch

# 2. Verify sync
versioneer verify

# 3. Commit
git add VERSION Cargo.toml Cargo.lock
git commit -m "chore: bump version to $(versioneer show)"

# 4. Tag and push
git tag v$(versioneer show)
git push origin main v$(versioneer show)
```

## Build System Support

| System | File | Example |
|--------|------|---------|
| Rust | Cargo.toml | `version = "1.2.3"` |
| Python | pyproject.toml | `version = "1.2.3"` |
| Node.js | package.json | `"version": "1.2.3"` |

The `VERSION` file in project root is the single source of truth.

## Best Practices

1. **Edit versions through versioneer only** (for build system files).
   Manual edits cause sync drift that leads to release failures.

2. **Verify synchronization before tagging**.
   Mismatched versions cause downstream build failures.

3. **Use v prefix for git tags** (e.g., v1.2.3).
   Standard CI/CD convention expected by GitHub Actions and semantic-release.

4. **Bump version before creating tags**.
   Tags pointing to unbumped versions create orphan releases.

5. **Commit version bumps separately from feature commits**.
   Clean version commits enable `git bisect` and changelog generation.

**See `resources/workflows.md` for complete guidelines.**

## Common Issues

| Problem | Solution |
|---------|----------|
| Command not found | Check PATH includes `$HOME/.local/bin` |
| VERSION file missing | `echo "0.1.0" > VERSION && versioneer sync` |
| Versions out of sync | `versioneer sync && versioneer verify` |
| Wrong version | `versioneer reset X.Y.Z && versioneer patch` |

**See `resources/troubleshooting.md` for detailed solutions.**

## Notes

- Versioneer is v2.0.3 as of October 2025
- VERSION file is the single source of truth
- Use semantic versioning consistently