# Releasing
Releases are automated with [release-plz](https://release-plz.dev) using a Release PR flow.
## Packages
- `getargs-derive`: the public crate. It is tagged `vX.Y.Z` and gets a GitHub release.
- `getargs-derive-macros`: the internal proc-macro implementation crate. It is published to crates.io only because `getargs-derive` depends on it. It is not tagged, has no GitHub release and is not meant for direct use.
Both crates share a single version defined in `[workspace.package]` in the root `Cargo.toml`. `getargs-derive` depends on `getargs-derive-macros` with an exact `=X.Y.Z` requirement, and the two crates are always bumped together (`version_group` in `release-plz.toml`). CI fails if the versions or the pin diverge.
## Flow
1. Changes are merged to `main`. CI runs, nothing is published.
2. The `Release` workflow opens or updates a Release PR that bumps the version, updates `CHANGELOG.md` and `Cargo.lock`.
3. Review the Release PR. Edit the version or the changelog in the PR if needed. When editing the version, update `[workspace.package].version` and the `=X.Y.Z` pin of `getargs-derive-macros` together.
4. Merge the Release PR when a release is wanted. The `Release` workflow then validates the workspace (version consistency, tests, `cargo package`), publishes `getargs-derive-macros` then `getargs-derive` to crates.io, creates the `vX.Y.Z` tag and the GitHub release with the changelog of that version.
Ordinary merges never publish: `release_always = false` restricts publishing to merged Release PRs. If validation fails, nothing is published.
## SemVer policy
Pull requests are squash-merged, so each pull request title becomes one commit on `main`. The `PR Title` workflow requires titles to follow [Conventional Commits](https://www.conventionalcommits.org) (`feat: ...`, `fix: ...`, `feat!: ...`). Merge commits and release commits are left out of the changelog.
The proposed bump is derived from these commits since the last release:
| `fix:` and other types | patch | patch |
| `feat:` | minor | patch |
| `feat!:`, `fix!:` or `BREAKING CHANGE:` footer | major | minor |
[cargo-semver-checks](https://github.com/obi1kenobi/cargo-semver-checks) runs on the Release PR and reports public API breaking changes in the PR body. If it detects a breaking change, the bump is raised accordingly. The maintainer has the final say and may change the version in the Release PR.
## Changelog
`CHANGELOG.md` is generated by release-plz with git-cliff using the `[changelog]` section of `release-plz.toml`. It covers the commits since the previous release, including those touching `macros/`, and its entry for the release is used as the Release PR content and the GitHub release body.
## Required setup
- Repository secret `CARGO_REGISTRY_TOKEN`: a crates.io API token with the `publish-new` and `publish-update` scopes.
- Settings > Actions > General > Workflow permissions: enable "Allow GitHub Actions to create and approve pull requests". Alternatively, replace `GITHUB_TOKEN` in the `release-plz-pr` job with a personal access token, which also lets CI run on the Release PR (pull requests opened with `GITHUB_TOKEN` do not trigger other workflows).