# Commits & Versioning

pman uses **[Conventional Commits](https://www.conventionalcommits.org/) +
[release-plz](https://release-plz.dev/)** for fully automated
semantic versioning.  You never need to manually decide or type a version number.

## How it works

```
Developer writes conventional commits
         │
         ▼
push / merge to main
         │
         ▼
release-plz workflow (release-plz.yml)
  • reads commits since last tag
  • computes next SemVer bump
  • updates Cargo.toml + CHANGELOG.md
  • commits directly to main (no PR review needed)
  • creates annotated tag (e.g. v0.2.0)
  • the version-bump commit uses "chore(release):" prefix
    so the workflow skips itself on re-trigger (no infinite loop)
         │
         ▼
release workflow (main.yml) triggers on the tag
  • runs tests
  • builds Linux / macOS / Windows binaries
  • creates GitHub Release with all binaries
```

## Commit message format

Every commit that reaches `main` must use the
[Conventional Commits](https://www.conventionalcommits.org/) format:

```
<type>[optional scope]: <short description>

[optional body]

[optional footer(s)]
```

### Version bump rules

| Commit prefix | Example | Version bump |
|---------------|---------|:------------:|
| `fix:` | `fix: handle empty version in POM` | patch `0.1.0 → 0.1.1` |
| `feat:` | `feat: parallel dependency download` | minor `0.1.0 → 0.2.0` |
| `feat!:` or `BREAKING CHANGE:` footer | `feat!: rename compile goal to build` | minor (0.x) `0.1.0 → 0.2.0`; major (≥1.x) `1.0.0 → 2.0.0` |
| `chore:`, `docs:`, `test:`, `refactor:`, `style:` | `docs: add benchmark table` | _no bump_ |

> **Tip:** If a PR contains only `chore:`/`docs:` commits, no release PR is
> opened — this is correct behaviour for changes that don't affect users.

## Types reference

| Type | When to use |
|------|-------------|
| `feat` | New user-visible feature |
| `fix` | Bug fix |
| `refactor` | Code change with no user-visible effect |
| `perf` | Performance improvement (treated as `fix` for bump purposes) |
| `docs` | Documentation only |
| `test` | Test additions or fixes |
| `chore` | Build scripts, CI, dependency updates |
| `style` | Formatting, whitespace |
