Skip to content

RELEASING.md

Latest commit

 

History

History
66 lines (38 loc) · 2.65 KB

RELEASING.md

File metadata and controls

66 lines (38 loc) · 2.65 KB

Releasing vitaminc

This project uses release-plz to automate versioning, changelog generation, and publishing to crates.io.

How it works

1. You push code to main

Merge your feature/fix PRs to main as usual. Use conventional commits (feat:, fix:, etc.) — these feed into the auto-generated changelog.

2. release-plz creates a release PR

On every push to main, the release-plz GitHub Action runs and creates (or updates) a release PR. This PR contains:

  • Version bumps in Cargo.toml (all 12 crates are bumped together)
  • Updated CHANGELOG.md files with entries generated by git-cliff from commit messages

3. You rewrite the changelog

The auto-generated entries are a baseline — a reminder of what changed, not the final copy. Before merging the release PR:

  • Review the generated changelog entries
  • Rewrite them to be clear, user-facing descriptions
  • Use Claude or another AI tool to help draft better entries

4. Merge the release PR

Once the changelog is ready, merge the release PR. This triggers the release job which:

  • Publishes all crates to crates.io
  • Creates git tags for each crate
  • Creates GitHub releases

Configuration

File Purpose
release-plz.toml release-plz config — version groups, feature flags
cliff.toml git-cliff config — how commits map to changelog entries
.github/workflows/release-plz.yml GitHub Actions workflow

All crates release together

All 12 workspace crates are in a single version_group. This means every release bumps all crates to the same version, regardless of which crates had changes. This keeps version alignment simple.

Secrets

The GitHub Action requires a CARGO_REGISTRY_TOKEN secret for crates.io publishing. This must be added to the repository's GitHub secrets.

Semver checking

release-plz runs cargo-semver-checks before releasing. If you accidentally introduce a breaking change without a major version bump, the release PR will flag it.

FAQ

Does a release PR get created on every merge to main?

release-plz doesn't create a new PR each time — it updates the same open release PR. So commits accumulate in a single PR until you merge it.

Do we have to merge the release PR every time?

No. You can let changes pile up and merge the release PR whenever you're ready to cut a release. It's a standing "release when ready" PR.

What happens if we skip one?

Nothing bad. The next push to main updates the existing release PR with the additional changes. The changelog and version bump will reflect everything since the last release.
⚡